name	aigon-feature-transfer
description	Transfer feature <ID> from its current agent to a different agent — preserves commits and in-flight work

aigon-feature-transfer

Hand a stuck or paywalled in-progress feature from its current agent to a different agent, without losing commits or in-flight work. Intended for:

An agent hitting a usage/token limit mid-implementation (Codex paywall, Claude 5h limit).
An agent stalling on a prompt, auth flow, or tool confusion that won't resolve itself.
A human deciding that a different agent (e.g. Claude Code) should take over from here.

The worktree, commits, branch, and workflow history are all preserved. Only the active agent changes.

Usage

aigon feature-transfer $1 --to=<agent> [--reason="..."] [--no-launch]

Flags:

--to=<agent> (required) — target agent id (e.g. cc, cx, gg, cu).
--reason="..." — free-text reason recorded in the transfer briefing.
--no-launch — do the transfer but don't auto-spawn the new agent; handy for scripted orchestration.

What it does (in order)

Captures the last ~3000 lines from every live tmux pane for the feature.
Writes a briefing to docs/specs/features/logs/feature-<ID>-transfer-<timestamp>.md — last commits, uncommitted diff, pane tails, and next-steps for the new agent.
Commits any uncommitted work in the worktree as wip(transfer): save <old> state before handoff to <new> so nothing is lost by the directory move.
Kills the old agent's tmux sessions and removes its heartbeat file.
Moves the worktree with git worktree move — directory renames from feature-<ID>-<old>-<desc>/ to feature-<ID>-<new>-<desc>/. The branch name is preserved (it encodes who originally started the work — not a problem, it's cosmetic after merge).
Re-seeds the workflow engine by emitting a fresh feature.started event so the dashboard and snapshot reflect the new agent. Prior events stay in history.
Launches the new agent with aigon feature-do <ID> --agent=<new> unless --no-launch was passed.

The new agent's first task is to read the briefing and the wip(transfer) commit before doing anything else — the briefing lays out exactly where the previous agent stopped and why.

Examples

# Codex hit its usage limit — pick up with Claude Code.
aigon feature-transfer 306 --to=cc --reason="cx hit GPT-5 usage limit, 8h wait"

# Same thing, but don't auto-start cc — useful in scripts that want to
# do their own launch or schedule it for later.
aigon feature-transfer 308 --to=cc --reason="auto-failover" --no-launch

aigon feature-reset <ID> — nukes the feature back to backlog (destroys commits). Use this only when you want to start over.
aigon sessions-close <ID> — only kills tmux sessions. The transfer command calls this internally.
Auto-failover (when enabled in your Aigon config) will invoke this command automatically when it detects a usage-limit panel in an agent's output.

aigon-feature-transfer

Hand a stuck or paywalled in-progress feature from its current agent to a different agent, without losing commits or in-flight work. Intended for:

An agent hitting a usage/token limit mid-implementation (Codex paywall, Claude 5h limit).

An agent stalling on a prompt, auth flow, or tool confusion that won't resolve itself.

A human deciding that a different agent (e.g. Claude Code) should take over from here.

The worktree, commits, branch, and workflow history are all preserved. Only the active agent changes.

Usage

aigon feature-transfer $1 --to=<agent> [--reason="..."] [--no-launch]

Flags:

--to=<agent> (required) — target agent id (e.g. cc, cx, gg, cu).

--reason="..." — free-text reason recorded in the transfer briefing.

--no-launch — do the transfer but don't auto-spawn the new agent; handy for scripted orchestration.

What it does (in order)

Captures the last ~3000 lines from every live tmux pane for the feature.

Writes a briefing to docs/specs/features/logs/feature-<ID>-transfer-<timestamp>.md — last commits, uncommitted diff, pane tails, and next-steps for the new agent.

Commits any uncommitted work in the worktree as wip(transfer): save <old> state before handoff to <new> so nothing is lost by the directory move.

Kills the old agent's tmux sessions and removes its heartbeat file.

Moves the worktree with git worktree move — directory renames from feature-<ID>-<old>-<desc>/ to feature-<ID>-<new>-<desc>/. The branch name is preserved (it encodes who originally started the work — not a problem, it's cosmetic after merge).

Re-seeds the workflow engine by emitting a fresh feature.started event so the dashboard and snapshot reflect the new agent. Prior events stay in history.

Launches the new agent with aigon feature-do <ID> --agent=<new> unless --no-launch was passed.

The new agent's first task is to read the briefing and the wip(transfer) commit before doing anything else — the briefing lays out exactly where the previous agent stopped and why.

Examples

# Codex hit its usage limit — pick up with Claude Code. aigon feature-transfer 306 --to=cc --reason="cx hit GPT-5 usage limit, 8h wait" # Same thing, but don't auto-start cc — useful in scripts that want to # do their own launch or schedule it for later. aigon feature-transfer 308 --to=cc --reason="auto-failover" --no-launch

aigon feature-reset <ID> — nukes the feature back to backlog (destroys commits). Use this only when you want to start over.

aigon sessions-close <ID> — only kills tmux sessions. The transfer command calls this internally.

Auto-failover (when enabled in your Aigon config) will invoke this command automatically when it detects a usage-limit panel in an agent's output.

aigon-feature-transfer