Neo

Neo is a fast, minimalist coding agent written in Go.

An interactive terminal UI lets you chat with the agent directly — watch it read
files, run commands, and make edits in real time. The codebase is intentionally
small and modular: a policy-free core agent loop, with capabilities layered on
top as independent, feature-flagged modules.

Features

• Interactive chat. neo opens a Bubble Tea terminal UI. Type a task and
  watch the agent work.
• Small tool surface. bash, read_file, write_file, edit_file — inspectable
  and easy to reason about.
• AGENTS.md support. Drop an AGENTS.md in your project (or ~/.neo/) and
  its guidance is loaded into the agent's system prompt. Feature-flagged.
• Skills. Reusable prompt snippets in .neo/skills/<name>/SKILL.md. Mention
  $name in a message and the skill's instructions are expanded into that turn.
• Modular core. The agent loop knows nothing about coding, files, or project
  context — capabilities are injected and can be toggled in config.

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 release archive from GitHub Releases, verifies its checksum when
available, 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

Homebrew

brew install --cask owainlewis/tap/neo

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

Usage

# Interactive terminal chat (default)
neo

# Same thing, explicit
neo chat

neo help

# Saved sessions
neo sessions
neo resume <session-id>

Commands

Sessions

Neo saves chat sessions under ~/.neo/sessions/ so conversations can be
resumed later. Session files contain the agent transcript, basic metadata such
as cwd and model, and tool call/result messages needed to continue the model
conversation.

neo sessions        # list recent sessions
neo resume <id>     # reopen a saved session

Future gateways should map transport sessions onto the same store instead of
creating separate transcript formats. For example, a Telegram DM can map
telegram:chat:<id> to a Neo session, and a Slack thread can map
slack:channel:<id>:thread:<ts> to a Neo session.

AGENTS.md

Neo loads project instructions from AGENTS.md into the chat system prompt.
It discovers, in increasing priority:

1. ~/.neo/AGENTS.md — user-global guidance
2. AGENTS.md from the repository root down to your working directory

Disable it by setting the feature flag to false (see Configuration).

Skills

Skills are reusable prompt snippets you invoke on demand. Each lives at
.neo/skills/<name>/SKILL.md (project) or ~/.neo/skills/<name>/SKILL.md
(global), with simple frontmatter:

---
name: review
description: review the current diff for correctness and broken contracts
---

You are reviewing a code change. Work from the actual diff…

Neo advertises each skill's name + description in the system prompt (so the
model knows they exist), and when you mention $name in a message it expands
that skill's full body into the turn:

use the $review skill on my changes

Project skills override global ones of the same name. This repo ships
$review and $commit under .neo/skills/ as working examples. Disable the
feature by setting skills: false (see Configuration).

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 by the agent. Default: claude-opus-4-8
model: claude-opus-4-8

# Optional, layered capabilities. Each defaults to on when omitted; set a flag
# to false to disable it. The core agent loop is never affected by these.
features:
  agents_file: true   # load AGENTS.md into the system prompt
  skills: true        # discover .neo/skills, advertise them, expand $name
  prompt_caching: true # cache the static system prompt prefix

Tools

The agent has four built-in tools:

Project Layout

cmd/neo/                CLI entry point and command dispatch
internal/agent/         Core agent loop and event model
internal/config/        Config loading and feature flags
internal/config/defaults/   Embedded neo.yaml
internal/llm/           Provider interface + Anthropic client
internal/projectctx/    AGENTS.md discovery and system-prompt injection
internal/session/       Saved session metadata and transcripts
internal/skills/        skill discovery, catalog, and $name expansion
internal/tools/         bash, read_file, write_file, edit_file implementations
internal/tui/           Bubble Tea terminal UI

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 ./... && golangci-lint run
just clean        # remove the ./neo binary

Install golangci-lint to run just lint
locally. CI runs the pinned linter version from .github/workflows/ci.yml.

Releasing

Releases are built by GitHub Actions when a v* tag is pushed:

git tag v1.2.3
git push origin v1.2.3

The release workflow runs tests, builds Linux and macOS binaries for amd64
and arm64, publishes GitHub release notes and checksums, and updates the
Homebrew cask in owainlewis/homebrew-tap.

The Homebrew tap update requires a repository secret named
HOMEBREW_TAP_GITHUB_TOKEN with write access to owainlewis/homebrew-tap.

License

MIT © Neo Contributors