Agent Workflow

The agent workflow is the core capability of the Edsger CLI. When you run edsger with no arguments, it starts a long-running process that autonomously discovers, claims, and processes features from the Edsger platform.

Why an Agent Workflow

Software development involves many repetitive phases: analyzing requirements, creating user stories, designing architecture, writing code, running tests, creating pull requests, reviewing code, and iterating on feedback. Each of these can be automated with AI, but orchestrating them into a reliable, end-to-end pipeline requires more than a simple script.

The agent workflow solves this by providing:

• Cross-product discovery — Automatically finds work across all products you have access to, not just one
• Concurrent processing — Processes multiple features simultaneously in isolated workers
• Crash resilience — One failed feature doesn't affect others; failures are retried with cooldown
• Verification loops — Each phase can be verified and re-run with feedback until quality criteria are met
• Platform sync — Every status change, result, and log is synced to the Edsger platform in real-time
• Human-in-the-loop — Verification gates and approval configurations let your team maintain control

How It Works

Starting the Agent

# Default: 3 concurrent features, 30s polling
edsger

# Custom concurrency
edsger --concurrency 5

# Verbose logging to see all details
edsger --verbose

The Main Loop

Once started, the agent follows this cycle:

┌──────────────────────────────────────┐
│           Agent Starts               │
│  - Register session with server      │
│  - Start auto-update checker         │
│  - Start chat worker subprocess      │
│  - Create workspace directory        │
└──────────────┬───────────────────────┘
               │
               ▼
┌──────────────────────────────────────┐
│      Poll for Ready Features         │◄──── Every 30s
│  - Call MCP: list all ready_for_ai   │      (configurable)
│  - Filter out: already processing,   │
│    recently failed, max-retried      │
│  - Calculate available worker slots  │
└──────────────┬───────────────────────┘
               │
               ▼
┌──────────────────────────────────────┐
│      Claim & Start Workers           │
│  - Pick features up to slot count    │
│  - For each feature:                 │
│    1. Get GitHub config              │
│    2. Clone or reuse repo            │
│    3. Fork worker child process      │
│    4. Set timeout timer              │
└──────────────┬───────────────────────┘
               │
               ▼
┌──────────────────────────────────────┐
│      Workers Run Independently       │
│  - Each in its own process + cwd     │
│  - Execute phase pipeline            │
│  - Report results via IPC            │
│  - On success: feature completed     │
│  - On failure: retry or skip         │
└──────────────────────────────────────┘

Feature Discovery

Every polling cycle, the agent calls the MCP server to list all features across all products that are in ready_for_ai or assigned_to_ai status. Features are then filtered:

• Already processing — Skip features that have an active worker
• Recently failed — Skip features within the retry cooldown period (default: 5 minutes)
• Max retries exceeded — Skip features that have failed maxRetries times (default: 3)
• Updated after failure — If a feature was updated on the platform after its last failure (e.g., someone provided feedback), it is eligible for retry regardless of cooldown

Worker Isolation

Each feature runs in its own forked Node.js process with:

• Isolated working directory — The repository is cloned to ~/edsger/{featureId}/ and the worker's cwd is set to that path
• Isolated memory — Each worker is a separate Node.js process (~50-80MB)
• IPC communication — Workers report logs and results back to the parent process via Node.js IPC channels
• Timeout enforcement — Each worker has a configurable timeout (default: 30 minutes). If exceeded, the worker receives SIGTERM, then SIGKILL after 10 seconds

Workspace Management

The CLI manages a workspace directory for cloned repositories:

• Location — ~/edsger/ by default (or ./edsger/ if you're already in a directory named edsger)
• Feature repos — Each feature gets its own subdirectory: ~/edsger/{featureId}/
• Reuse — If a feature's repo already exists, the CLI reuses it (fetches latest changes) instead of re-cloning
• Secure cloning — GitHub tokens are passed via git -c credential.helper instead of being embedded in the clone URL, so they don't appear in process listings

Chat Worker

A parallel chat worker subprocess runs alongside the main agent:

• Monitors platform chat — Processes incoming chat messages from the web UI
• Receives phase events — Gets notified when feature workers start, complete, or fail phases
• Independent lifecycle — If the chat worker crashes, the main agent continues processing features

Retry Logic

When a feature fails:

1. The failure count is incremented
2. A cooldown timer starts (default: 5 minutes)
3. On the next poll after cooldown, the feature is picked up again
4. After maxRetries failures (default: 3), the feature is permanently skipped

Override: If someone updates the feature on the platform (e.g., provides feedback, changes configuration, or adjusts the execution mode), the feature becomes eligible for processing immediately — the retry counter and cooldown are bypassed.

Graceful Shutdown

When you press Ctrl+C (or the process receives SIGINT/SIGTERM):

1. Polling stops immediately
2. The chat worker receives SIGTERM
3. All active feature workers receive SIGTERM
4. Worker timeout timers are cleared
5. Final statistics are displayed (features processed, succeeded, failed)
6. The CLI session is deregistered from the platform

Execution Modes

Each feature on the Edsger platform has an execution mode that determines which phases the CLI runs. This is configured per-feature in the web UI when you set a feature to "Ready for AI".

Full Pipeline

Mode: full_pipeline

Runs all phases from start to finish:

feature-analysis → technical-design → code-implementation →
functional-testing → pull-request → code-review →
code-refine → code-testing → ready-for-review

Single Phase

Run only one specific phase:

From Phase to End

Start at a specific phase and run everything after it:

Autonomous Mode

Mode: autonomous

AI independently discovers improvements and implements them in a time-limited loop. No predefined phases — the AI decides what to work on.

Custom Mode

Mode: custom

User-selected subset of phases. Configured in the web UI when setting the feature to "Ready for AI".

Feature Status Flow

As the agent processes a feature, it transitions through these statuses:

backlog
  └→ ready_for_ai                  (set by human in web UI)
       └→ assigned_to_ai            (claimed by CLI)
            └→ feature_analysis
                 └→ feature_analysis_verification
                      └→ user_stories_analysis
                           └→ user_stories_analysis_verification
                                └→ test_cases_analysis
                                     └→ test_cases_analysis_verification
                                          └→ technical_design
                                               └→ technical_design_verification
                                                    └→ branch_planning
                                                         └→ branch_planning_verification
                                                              └→ code_implementation
                                                                   └→ code_implementation_verification
                                                                        └→ pr_splitting
                                                                             └→ pr_splitting_verification
                                                                                  └→ pr_execution
                                                                                       └→ code_refine
                                                                                            └→ code_refine_verification
                                                                                                 └→ bug_fixing
                                                                                                      └→ code_review
                                                                                                           └→ functional_testing
                                                                                                                └→ ready_for_review
                                                                                                                     └→ shipped

Each *_verification status is a gate where the AI (or a human, depending on your approval configuration) verifies the phase output. If verification fails, the phase is re-run with feedback about what needs to change.

Session Management

The CLI registers a session with the Edsger platform when it starts:

• Session registration — Tells the platform a CLI instance is running, with heartbeat
• Heartbeat — Periodic signal sent to the platform so it knows the CLI is alive (includes current feature being processed)
• Remote control — The platform can pause/resume processing via session commands
• Deregistration — On shutdown, the session is cleaned up

Logging

All CLI output is:

1. Displayed in the terminal — Color-coded with the CLI version prefix
2. Synced to the platform — Logs are buffered and flushed to the Edsger platform every 5 seconds via the cli_logs/batch MCP method

This means you can monitor CLI activity from the web UI even when the CLI is running on a remote machine or CI server.

Log levels:

• Info — Normal operational messages (phase starts, feature claims, etc.)
• Success — Phase completions, feature completions
• Warning — Non-critical issues (git fetch failures, optional features unavailable)
• Error — Phase failures, worker crashes, API errors

Feature worker logs are prefixed with the feature name (e.g., [Add dark mode] Phase started: technical-design), making it easy to follow multiple concurrent features.