Coding Agents

This document covers how code_with_agent and code_with_team execute external coding CLIs.

What these tools are

• code_with_agent: run one coding worker CLI (claude, codex, or kimi)
• code_with_team: decompose a task and run multiple code_with_agent workers in parallel

These are separate from in-process tool calling (Read, Write, Glob, Bash, Fetch, Browser).

Exact CLI commands

Commands are constructed by buildCodeAgentArgs() in src/code-agents/utils.ts.

Claude worker

claude -p --verbose --output-format stream-json --dangerously-skip-permissions \
  --allowedTools Edit --allowedTools Read --allowedTools Write --allowedTools Bash --allowedTools Glob --allowedTools Grep \
  --max-turns <N> \
  --append-system-prompt "Output text only..." \
  [--model <model>] \
  <task>

Codex worker

codex exec --full-auto --json --color never \
  [-C <workdir>] \
  [-m <model>] \
  <task>

Kimi worker

kimi --yolo -p <task> \
  [-w <workdir>] \
  [-m <model>]

Code locations

• Tool definitions: src/tools/definitions.ts
• Runtime orchestration: src/code-agents/index.ts
• CLI argument builder: src/code-agents/utils.ts

Sandbox

Coding agents run on the host, not inside the sandbox. They spawn external CLI processes (claude, codex, kimi) that manage their own tool execution and file access directly on your machine.

The sandbox only applies to the built-in Bash tool used by the main agent. If you need sandboxed code execution, use a cron job or the main agent's Bash tool instead of code_with_agent.

CLI monitoring

skimpyclaw agents              # List all agents (active + recent)
skimpyclaw agents <id>         # Show details for an agent (task, children, live output)
skimpyclaw agents <id> --follow  # Follow live output (refreshes every 3s until done)

For team coordinators, this shows all child agents grouped by wave with status, elapsed time, and live output.

The dashboard (/dashboard → Coding page) also shows real-time agent status with expandable subagent cards.

Discord notifications

When a coding agent starts from a Discord message, a thread is automatically created from the triggering message (unless threadedReplies: false in config). Status updates and completion results route to the thread first, falling back to the default channel.

Notification format:

• Start: Response includes "Started coding agent ca-N" which triggers thread creation
• Success: ✅ Coding agent {id} completed ({duration}). Task: {preview}. Result: {output}
• Failure: Includes error details and output snippet
• Team tasks: Structured summary with per-child status and validation results

Notifications are also sent to the active channel (Telegram or Discord) via sendActiveChannelProactiveMessage(). Long messages are chunked at 1900 characters for Discord.

Selection behavior

• Agent selection supports claude, codex, kimi
• codeAgents.defaultAgent is used when no explicit agent is passed
• Legacy-like values (claude-think, codex5.3, etc.) normalize to supported agent IDs

Long-running tasks

For tasks that should run on a schedule or without a user present (nightly syncs, daily digests, background refactors), use cron instead of a coding agent triggered ad-hoc:

{
  "cron": {
    "jobs": [
      {
        "name": "nightly-refactor",
        "schedule": "0 2 * * *",
        "payload": {
          "agentTurn": {
            "agentId": "main",
            "prompt": "Run the nightly refactor script in ~/Sites/myproject and commit the results."
          }
        }
      }
    ]
  }
}

Cron jobs run with the full agent loop (tools, coding agents, file access) and their output is logged to ~/.skimpyclaw/logs/cron/.