README
¶
Fast · Workflow-first · Open source
Neo
Built for real engineering.
Neo turns complex repository work into a visible workflow. Keep the plan, tools, tests, reviews, and delivery moving in one terminal.
The whole workflow, not just the edit
Neo works where engineering happens: in your repository, with your project instructions, tools, and git history. Give it a real task and follow the work from first inspection to tested change.
- Visible by default. See the plan, active work, tool activity, tests, and delegated tasks without reading a wall of chat.
- One coordinator, focused workers. Delegate bounded work to subagents and bring their evidence back into one coherent workflow.
- Your model, your choice. Use Anthropic, OpenAI, Google Gemini, or OpenRouter, and switch models for the active provider without leaving the terminal.
- Control that fits the task. Choose trusted, approval-based, or read-only permissions. Steer active work or queue the next instruction at any time.
- A small, dependable foundation. One native Go binary, built-in tools, local sessions, no runtime or plugin stack, and no product telemetry.
Quick start
1. Install Neo
curl -fsSL https://raw.githubusercontent.com/owainlewis/neo/main/install.sh | bash
The installer downloads the matching GitHub release and verifies its SHA-256 checksum before installing it. See the installation guide for version pinning and custom install directories.
2. Connect a model
Neo uses Anthropic by default:
export ANTHROPIC_API_KEY="sk-ant-..."
Prefer OpenAI, Gemini, or OpenRouter? The
provider guide covers API keys,
ChatGPT/Codex subscription login, and the small neo.yaml config.
3. Start in a repository
cd your-project
neo
Then give Neo the outcome and the process you expect:
Find the cause of the failing test, plan the fix, implement it, run the
relevant checks, and review the final diff.
Make the workflow yours
Neo follows repository instructions from AGENTS.md and reusable skills from
.neo/skills/. Define how your team plans, tests, reviews, and ships once, then
let every task follow the same process.
Continue with the user guide, or explore the technical reference for configuration, permissions, sessions, tools, skills, and the CLI.
Contributing
git clone https://github.com/owainlewis/neo.git
cd neo
go test ./...
go run ./cmd/neo
Start with the developer documentation before changing the agent loop, providers, tools, or TUI.
License
MIT © Neo Contributors
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
neo
command
|
|
|
internal
|
|
|
atomicfile
Package atomicfile provides small helpers for crash-safe file replacement.
|
Package atomicfile provides small helpers for crash-safe file replacement. |
|
config
Package config loads neo's single configuration file (neo.yaml / ~/.neo/config.yaml / embedded default).
|
Package config loads neo's single configuration file (neo.yaml / ~/.neo/config.yaml / embedded default). |
|
factory
Package factory supervises chat-spawned subagents.
|
Package factory supervises chat-spawned subagents. |
|
llm/chatcompletions
Package chatcompletions implements llm.Provider for OpenAI-compatible Chat Completions APIs.
|
Package chatcompletions implements llm.Provider for OpenAI-compatible Chat Completions APIs. |
|
llm/google
Package google implements the llm.Provider interface against the Google Gemini GenerateContent API.
|
Package google implements the llm.Provider interface against the Google Gemini GenerateContent API. |
|
llm/llmtest
Package llmtest provides test doubles for the llm.Provider interface.
|
Package llmtest provides test doubles for the llm.Provider interface. |
|
llm/openai
Package openai implements the llm.Provider interface against OpenAI's Responses API (https://platform.openai.com/docs/api-reference/responses).
|
Package openai implements the llm.Provider interface against OpenAI's Responses API (https://platform.openai.com/docs/api-reference/responses). |
|
llm/openrouter
Package openrouter implements the llm.Provider interface against OpenRouter's OpenAI-compatible Chat Completions API.
|
Package openrouter implements the llm.Provider interface against OpenRouter's OpenAI-compatible Chat Completions API. |
|
projectctx
Package projectctx discovers project-level instruction files (AGENTS.md) and composes them into the agent's system prompt as a labelled section.
|
Package projectctx discovers project-level instruction files (AGENTS.md) and composes them into the agent's system prompt as a labelled section. |
|
skills
Package skills discovers user-defined skills (SKILL.md files) and surfaces them to the chat agent in three ways:
|
Package skills discovers user-defined skills (SKILL.md files) and surfaces them to the chat agent in three ways: |
|
workspace
Package workspace locates the project on disk — the repository root and the chain of directories from the working directory up to it.
|
Package workspace locates the project on disk — the repository root and the chain of directories from the working directory up to it. |