CodeAct Agent

A CodeAct-style AI agent written in Go.

What it does

The agent receives a natural-language task and solves it by generating and executing shell commands in a loop — no fixed tool schemas, no JSON function calls. The LLM writes real code; the agent runs it, feeds the output back, and repeats until the model produces a final answer without any <execute> blocks.

User task
   │
   ▼
┌──────────┐   prompt + history    ┌────────────┐
│  Agent   │ ─────────────────────▶│  Claude    │
│  loop    │                       │  (LLM)     │
│          │ ◀─────────────────────│            │
└──────────┘   reply with          └────────────┘
     │         <execute> blocks
     │
     ▼  execute each block (bash / cmd.exe)
┌──────────┐
│ Executor │──▶ stdout / stderr
└──────────┘
     │
     ▼  [OBSERVATION] … [/OBSERVATION]
  (fed back as the next user message)
     │
     └─── loop until no <execute> blocks ──▶ Final Answer

How "code as action" works

Standard tool-use agents call a fixed list of JSON-schema functions. CodeAct agents instead generate shell code as their action primitive:

<execute>
find . -name "*.go" | xargs wc -l | sort -rn | head -10
</execute>

This gives the model loops, conditionals, pipes, and the full power of the shell — composed in a single action instead of many discrete tool calls.

Requirements

• Go 1.22+
• An Anthropic API key (ANTHROPIC_API_KEY)
• bash (Linux/macOS) or cmd.exe (Windows) — already on your system

Build

git clone <repo-url>
cd codeact-agent
go build -o agent ./cmd/agent

On Windows:

go build -o agent.exe ./cmd/agent

Run

export ANTHROPIC_API_KEY=sk-ant-...

# pass the task as an argument
./agent "find all .go files, count their lines, and show the top 5 by size"

# read task from stdin
echo "show disk usage of the current directory sorted by size" | ./agent -stdin

# use a specific working directory
./agent -workdir /path/to/project "list all TODO comments in Go files"

Flags

Flag	Default	Description
-workdir	.	Working directory for shell execution
-model	claude-sonnet-4-6	Anthropic model to use
-max-turns	20	Maximum LLM ↔ execution rounds
-timeout	30s	Per-execution timeout
-verbose	false	Print thoughts and observations to stderr
-stdin	false	Read task from stdin

Example session (verbose)

────────────────────────────────────────────────────────────
  CodeAct Agent
  model   : claude-sonnet-4-6
  workdir : /home/user/project
  task    : count how many Go files exist and total lines of code
────────────────────────────────────────────────────────────

--- turn 1 ---
[assistant]
I'll count the Go files and lines of code.

<execute>
find . -name "*.go" | wc -l
find . -name "*.go" -exec cat {} \; | wc -l
</execute>

[observation]
[OBSERVATION]
4
312
[/OBSERVATION]

--- turn 2 ---
[assistant]
There are 4 Go files with a total of 312 lines of code.

=== Final Answer ===
There are 4 Go files with a total of 312 lines of code.

Design choices

• No external dependencies — the entire project uses only the Go standard library. The Anthropic API is called via net/http directly.
• Shell as the action language — shell commands are universally available, expressive, and composable; no custom tool registry needed.
• Cross-platform — uses cmd.exe /c on Windows, bash -c (or sh -c) everywhere else.
• Context-aware — a context.Context flows through every layer; Ctrl-C cancels cleanly, and each execution has its own deadline.

Project structure

codeact-agent/
├── cmd/
│   └── agent/
│       └── main.go          # CLI — flags, wiring, signal handling
├── internal/
│   ├── llm/
│   │   └── client.go        # Anthropic Messages API (stdlib HTTP)
│   ├── executor/
│   │   └── executor.go      # Shell execution with timeout
│   └── agent/
│       ├── agent.go         # CodeAct loop
│       └── parser.go        # <execute> block extractor
├── go.mod
└── README.md