Agent Management

Experimental This feature currently works on macOS and Linux with ai-devkit from version 0.10.0. Behaviors and commands may change in future versions.

The agent command allows AI DevKit to detect, list, and interact with other AI agents running on your system. It acts as a central hub to find where your AI coding agents are working and quickly switch context to them.

For an interactive terminal UI that combines listing, previewing, messaging, starting, renaming, killing, and channel controls, see Agent Console.

To use the agent open command, your environment must meet these requirements:

• Operating System: macOS is currently the primary supported platform for terminal focusing. Linux detection may work, but terminal focus behavior depends on your terminal and desktop environment.
• Terminal Emulator: The agent must be running in one of the following:
  • tmux
  • iTerm2
  • Apple Terminal

[!NOTE] AI DevKit uses process detection and system automation (AppleScript) to locate and focus windows. Ensure you grant necessary permissions when prompted.

AI DevKit detects active sessions from the following tools:

• Claude Code: Automatically detects running claude processes and correlates them with your active projects.

• Codex: Detects running Codex sessions and exposes the same list, open, send, and detail workflows.

• Gemini CLI: Detects running Gemini CLI sessions and exposes them through the same agent management commands.

• GitHub Copilot: Detects running Copilot coding agent sessions and exposes them through the agent list, detail, and send workflows.

• opencode: Detects running opencode sessions and exposes them through the same agent management commands.

• Pi: Detects Pi sessions. For more accurate Pi integration, install the @ai-devkit/pi-session-tracker package inside Pi:

  pi install npm:@ai-devkit/pi-session-tracker
  

  The tracker gives AI DevKit better session information than process detection alone.

List all detected running agents.

ai-devkit agent list
ai-devkit agent list --json

Table output includes:

Agent	CWD	Type	Status	Working On	Active
my-project	~/code/my-project	Claude Code	🟢 run	implementing new feature	just now
website	~/code/website	Codex	⚪ idle	fixed css bug	10m ago

Use --json when you want the raw machine-readable agent list.

Focus the terminal window associated with a specific agent.

ai-devkit agent open <name>

This command finds the exact window (tmux pane, iTerm2 session, etc.) where the agent is running and brings it to the foreground.

Features:

• Fuzzy Matching: ai-devkit agent open my-proj will match my-project-name.
• Ambiguity Handling: If multiple agents match (e.g., web-frontend, web-backend), you will be prompted to select one.

Send a message directly to a running agent.

ai-devkit agent send "continue with the failing tests" --id my-project

If the agent is not currently waiting for input, AI DevKit warns you and still sends the message.

Inspect a running agent's conversation details.

ai-devkit agent detail --id my-project

Useful options:

• --json for machine-readable output
• --tail <n> to show only the last n messages
• --full to show the entire conversation history
• --verbose to include tool call and tool result details

1. Ensure the agent process (e.g., claude) is actually running.
2. Verify you are running AI DevKit in the same user context.

If agent open fails to focus the window:

1. Check Terminal Support: Ensure the agent is running in tmux, iTerm2, or Apple Terminal. VS Code terminal is strictly not supported for external focus control.
2. Check Permissions (macOS):
   • Go to System Settings > Privacy & Security > Accessibility.
   • Ensure your terminal (iTerm2, Terminal) or tmux has permission to control your computer.
   • If prompted during execution, click Allow.