Neo

Neo is a fast, minimalist coding agent with first-class workflow support, written in Go.

An interactive terminal UI lets you chat with the agent directly. A headless CLI lets you run repeatable multi-step flows in CI or from scripts — each step is a plain Markdown prompt file that you can read and edit without touching any code.

Features

• Interactive chat. neo chat opens a Bubble Tea terminal UI. Type a task, watch the agent read files, run commands, and make edits in real time.
• Multi-step flows. neo flow <name> "<task>" runs a named sequence of agent steps. Each step receives the outputs of all prior steps as context.
• Single-step runs. neo step <name> "<task>" runs one step prompt against a task — useful for iterating on a prompt without a full flow.
• Plain-text prompts. Step prompts are Markdown files (flows/*.md). Customize them by adding a flows/ directory to your project or ~/.neo/flows/.
• Per-step overrides. A step's Markdown file can carry optional YAML frontmatter to restrict its tool set or pin a specific model.
• Small tool surface. bash, read_file, write_file, edit_file — inspectable and easy to reason about.

Quick Start

Prerequisites: An Anthropic API key.

One-line install (recommended)

curl -fsSL https://raw.githubusercontent.com/owainlewis/neo/main/install.sh | bash

The script auto-detects your OS and architecture, downloads the matching pre-built binary from GitHub Releases, and installs it to ~/.local/bin. If no pre-built binary is available for your platform it falls back to go install (requires Go 1.25+).

Options:

# Pin a specific version
curl -fsSL .../install.sh | bash -s -- --version v1.2.3

# Install to a custom directory
curl -fsSL .../install.sh | bash -s -- --bin-dir /usr/local/bin

Manual install

git clone https://github.com/owainlewis/neo.git
cd neo
just build                          # or: go build -o neo ./cmd/neo
export ANTHROPIC_API_KEY="sk-ant-..."
./neo                               # opens the chat TUI (default)

just build stamps the current git description into the binary as the version shown on the splash screen (use just print-version to preview).

Install onto your $GOBIN path:

go install github.com/owainlewis/neo/cmd/neo@latest
neo chat

Usage

# Interactive terminal chat
neo chat

# Run the built-in "code" flow (write → review) against a task
neo flow code "Add request-cancellation support to the HTTP client"

# Run a single step headlessly
neo step write "Refactor the config loader"
neo step review "Check the current diff for blocking issues"

neo help

Commands

Command	Description
neo chat	Open the interactive terminal coding agent
neo flow <name> "<task>"	Run a named flow from neo.yaml
neo step <name> "<task>"	Run a single step prompt from flows/<name>.md
neo help	Show CLI help

Flows

A flow is a named sequence of steps defined in neo.yaml. The engine runs each step in order, passing prior step outputs as context. If a step reports failure and retry_from is set, the engine rewinds to that step and tries again (up to max_rounds times).

Built-in flow: code

flows:
  code:
    steps: [write, review]
    retry_from: write
    max_rounds: 2

Flow	Steps	Behaviour
code	write → review	Writes the change, then reviews it. Retries write if review fails.

Defining your own flows

Add a neo.yaml to your project (or ~/.neo/config.yaml globally):

model: claude-sonnet-4-6

flows:
  ship:
    steps: [write, test, review]
    retry_from: write
    max_rounds: 3

Then add the corresponding step prompts in flows/write.md, flows/test.md, and flows/review.md. Any step not found locally falls back to the embedded defaults.

Step Prompts

A step prompt is a Markdown file. It may include optional YAML frontmatter to restrict the tool set or override the model for that step:

---
tools: [bash, read_file]
model: claude-haiku-4-5
---

You are the REVIEW step of a coding flow.
…

Prompt resolution order (first match wins):

1. ./flows/<name>.md — project-local override
2. ~/.neo/flows/<name>.md — user-global override
3. Embedded defaults (shipped with the binary)

Configuration

Neo looks for a config file in this order:

1. ./neo.yaml — project config
2. ~/.neo/config.yaml — user config
3. Embedded defaults — no file required to get started

The only required environment variable is ANTHROPIC_API_KEY.

export ANTHROPIC_API_KEY="sk-ant-..."

neo.yaml reference:

# Model used for all steps unless overridden in frontmatter.
# Default: claude-sonnet-4-6
model: claude-sonnet-4-6

# Directory where step artifacts are written.
# Default: .agent/runs
artifacts_dir: .agent/runs

flows:
  code:
    steps: [write, review]
    retry_from: write   # rewind to this step on failure
    max_rounds: 2       # maximum retry rounds (0 or omitted = 1)

Tools

The agent has four built-in tools:

Tool	Description
bash	Run a shell command (2-minute timeout)
read_file	Read a file from disk
write_file	Create or overwrite a file
edit_file	Replace one exact string match in a file

Project Layout

cmd/neo/                CLI entry point and command dispatch
internal/agent/         Core agent loop and event model
internal/config/        Config loading, flow definitions, step resolution
internal/config/defaults/   Embedded neo.yaml and built-in step prompts
internal/artifact/      Per-run artifact storage (.agent/runs/)
internal/flow/          (reserved)
internal/phase/         Single-step runner
internal/tools/         bash, read_file, write_file, edit_file implementations
internal/tui/           Bubble Tea terminal UI
internal/workflow/      Multi-step workflow engine

Development

just is used as a task runner. All targets also work as plain go commands.

just build        # go build -o neo ./cmd/neo
just test         # go test ./...
just test-verbose # go test -v ./...
just install      # go install ./cmd/neo
just fmt          # gofmt -w .
just lint         # go vet ./...
just clean        # remove the ./neo binary

License

MIT © Neo Contributors