This guide covers the source layout, development workflow, and testing strategy for contributors.
- CLI entry point:
bin/imploidparses flags (--config,--install-commands,--version) and routes into the orchestrator or configuration helpers. - Core orchestration:
src/lib/orchestrator.tscoordinates repository polling, processor scheduling, and state tracking. - Processors:
src/lib/processors/claude.tsandsrc/lib/processors/codex.tsexecute the respective CLIs using the shared prompt insrc/lib/processors/prompt.ts. - State & repos:
src/lib/stateManager.tspersists progress under~/.imploid, whilesrc/lib/repoManager.tsmanages per-processor worktrees. - Claude commands installer:
src/lib/claudeCommandsInstaller.tsmirrors the publicHey-Diga/dotclaudecommands into.claude/commandswhen the CLI is invoked with--install-commands. - Processor configuration:
src/lib/config.tspersists which processors are enabled by default, and the CLI accepts--processorsto override the list at runtime.
src/
lib/
claudeCommandsInstaller.ts # Pulls command templates from Hey-Diga/dotclaude
config.ts # Configuration persistence and interactive wizard
orchestrator.ts # Main orchestrator loop
repoManager.ts # Git worktree management
stateManager.ts # Issue/process state tracking
processors/
claude.ts # Claude CLI runner
codex.ts # Codex CLI runner
prompt.ts # Shared issue prompt
shared.ts # Common helpers for processors
bin/
imploid # Bun CLI entry point
tests/
*.test.ts # Bun test suite mirrors src modules
bun install- Bun 1.2+ is required.
- GitHub CLI (
gh) must be installed and available inPATHfor orchestrator runs. - Configuration, state, and repo clones live under
~/.imploid.
bunx imploid --config # Interactive configuration wizard
bunx imploid # Run orchestrator using saved config
bunx imploid --install-commands # Refresh .claude/commands in the current repo
bunx imploid --processors claude # Override processors for a single run
bun test # Run the full Bun test suite
bun test tests/<file> # Target a specific test file- TypeScript with four-space indentation.
camelCasefor functions and variables;PascalCasefor classes and enums.- Prefer explicit return types and shared utilities in
src/lib. - Keep CLI-facing exports surfaced through
src/lib/index.tswhen needed.
- Use Bun’s test runner (
bun test). - Name new specs
<feature>.test.tsundertests/. - Mock shell/process utilities when executing external commands.
- Verify concurrency and repo state changes with targeted fixtures.
- Branch from
main(e.g.,feature/install-commands-flag). - Implement changes and update tests/documentation.
- Run
bun testand, if relevant, manual flows likebunx imploid --configorbunx imploid --install-commands. - Follow repository commit guidelines (present tense, reference issues in the body) before submitting a pull request.