# Exit Codes

This document describes the exit codes used by kugetsu commands.

## Exit Codes

| Exit Code | Meaning |
|-----------|---------|
| 0 | Success - operation completed successfully |
| 1 | General error - worktree/session/validation failed |
| 2 | Max concurrent agents reached (MAX_CONCURRENT_AGENTS limit) |

## Commands

### cmd_continue / cmd_start

The `cmd_continue` command (aliased to `cmd_start`) returns exit codes to indicate the result of the operation:

- **Exit 0**: Success - agent forked successfully
- **Exit 1**: General error - worktree/session/validation failed
- **Exit 2**: Max concurrent agents reached

### Internal Functions

#### fork_agent()

Forks a new agent session for a given worktree.

- **Return 0**: Success - agent forked successfully
- **Return 1**: General error - invalid worktree path or other failure

#### ensure_worktree()

Ensures a worktree exists for the given issue reference.

- **Return 0**: Success - worktree existed or was created
- **Return 1**: General error - base session not found or worktree creation failed
- **Return 2**: Max concurrent agents reached

## Daemon Integration

These exit codes are designed to help the queue daemon distinguish between recoverable and non-recoverable errors:

- **Exit 2 (max agents)**: This is a recoverable error - the daemon can retry later when agents become available
- **Exit 1 (general error)**: Non-recoverable - the task should be marked as failed

## MAX_CONCURRENT_AGENTS

The maximum number of concurrent development agents is controlled by the `MAX_CONCURRENT_AGENTS` configuration variable (default: 3).

Set this in your `config` file:

```bash
MAX_CONCURRENT_AGENTS=5
```

Or via environment variable:

```bash
export MAX_CONCURRENT_AGENTS=5
```