neo

neo is a Rust coding-agent harness for long-running autonomous software work.

Core Capabilities

• Multi-provider LLM runtime: OpenAI-compatible, OpenAI Codex account auth, Anthropic, Gemini, Ollama/Ollama Cloud, OpenRouter, OpenCode, OpenCode Go
• Tool loop with file IO, shell, web search, workers, browser control, and gateway routing
• Session persistence, resumable transcripts, and worktree-isolated workers
• Config-driven gateway routing with deterministic session-key generation
• CDP browser automation against Chrome/Chromium-compatible targets
• Ralph supervisor loop with fresh-session cycling, checkpointing, and host verification commands
• Always-on OpenClaw-style gateway daemon for routed channel ingress
• Team mode — reviewer agent evaluates every tool action before execution
• Image/SVG terminal rendering — inline unicode half-block art for PNG, JPEG, GIF, and SVG files
• Rich TUI — ratatui-based terminal UI with unicode art, tab completion, model/session/skill pickers

Build

$HOME/.cargo/bin/cargo test
$HOME/.cargo/bin/cargo build

Install

One-line installer for the current private repo:

gh api -H "Accept: application/vnd.github.raw" repos/AgentsLabs/neo/contents/install.sh | bash

This requires gh auth login first.

If the repository is later made public, the raw curl form also works:

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

Manual install with Cargo:

$HOME/.cargo/bin/cargo install --git https://github.com/AgentsLabs/neo.git --branch main --locked --force

Useful installer overrides:

REPO_URL=https://github.com/AgentsLabs/neo.git BRANCH=main INSTALL_ROOT=$HOME/.local curl -fsSL https://raw.githubusercontent.com/AgentsLabs/neo/main/install.sh | bash

After install, ensure your path includes the install root:

export PATH="$HOME/.local/bin:$PATH"

Quick Start

$HOME/.local/bin/neo

Run from source:

$HOME/.cargo/bin/cargo run

Useful commands:

• /login status
• /login codex
• /login ollama
• /setup provider-gateway
• /gateway show
• /gateway route slack group C123
• /browser status
• /browser tabs
• /browser open https://example.com
• /browser screenshot artifacts/page.png
• /ralph status
• /ralph run refactor the parser and verify with cargo test

TUI Mode (Terminal UI)

Start the full-screen terminal UI with --tui:

neo --tui
neo --tui --provider ollama --model llama3
neo --tui --team-mode

Feature Screenshots

These screenshots are captured from real Neo UI and documentation surfaces:

Feature	Screenshot
Full TUI command surface
TUI banner and status bar
Team-mode reviewer flow
Image/SVG terminal rendering
Vault command flow
Responsive docs on mobile

Layout

The TUI is split into three panes:

1. Header (top 4 lines) — NEO box-drawing logo, provider badge, model badge, workspace path, access level, worker ID, permission mode, team mode indicator, and real-time progress
2. Transcript (center, resizable) — scrollable conversation history with color-coded roles and unicode symbols
3. Input (bottom 4 lines) — command prompt with model, provider, and session ID

Keybindings

Unicode Art & Role Symbols

Each conversation role is prefixed with a distinct unicode symbol:

Image & SVG Rendering

Attach images (PNG, JPEG, GIF, SVG) for inline terminal preview:

/attach image diagram.png
/attach image screenshot.jpg
/attach image logo.svg

Images are rendered using unicode half-block art (▀/▄ characters) with 24-bit ANSI foreground/background colors. Each terminal cell displays 2 vertical pixels at native aspect ratio. SVGs are rasterized at render time via resvg.

Tab Completion

In the TUI, press Tab to:

• Commands: when input starts with /, cycle through all known commands
• File paths: when not a command, complete partial paths relative to the workspace

Model Picker

/models opens a keyboard-driven modal overlay:

• Type to filter models by name
• ↑/↓ to navigate
• Enter to select
• Esc to close
• Active model marked with ★

Session Picker

/session opens a session selection overlay:

• Lists all saved sessions
• ↑/↓ to navigate
• Enter to switch to a session (reloads full context)
• Esc to close

Skill Toggler

/skills opens a skill toggle overlay:

• Lists available skills with active/inactive state
• ↑/↓ to navigate
• Enter to toggle a skill on/off
• Active skills marked with ☒, inactive with ☐
• Esc to close

Search Picker

/search <query> opens a web search results overlay (requires --search or search_enabled=true):

• Shows title, URL, and snippet for each result
• ↑/↓ to navigate
• Enter to insert the selected URL into the input
• Esc to close

Help Overlay

Press ? to toggle a comprehensive help panel showing all keybindings and commands, organized with unicode section headers.

Rich TUI Direction

Recommended TUI feature/libs assessment:

• Keep ratatui + crossterm as the base. They already cover layout, gauges, lists, modals, scrollbars, styling, and terminal events with minimal dependency risk.
• Consider tui-textarea later for multiline editing if Neo needs IDE-like prompt composition.
• Consider tui-input later for reusable input state, but it overlaps with the current custom command/path completion.
• Avoid switching to a different TUI framework until the existing Ratatui UI is modularized.

Implemented choice: a Ratatui status rail appears on wide terminals. It shows session/message counts, tool/error counts, active skills, memory notes, queued attachments, context-size gauge, scrollback gauge, and quick command tips.

Prompt Attachments

Queue file or image content for the next LLM prompt:

/attach file data.csv          # queue a text file
/attach image architecture.png # queue an image (rendered inline in TUI)
/attach show                   # show queued attachments
/attach clear                  # clear queued attachments

Team Mode

Team mode enables a reviewer agent that critically evaluates every tool action before execution:

neo --team-mode
neo --tui --team-mode

Config

{
  "team_mode": true
}

How It Works

1. The LLM proposes a tool action (file write, shell command, search, etc.)
2. Before execution, the proposed action is sent to a second LLM call (the reviewer)
3. The reviewer returns one of three verdicts:
   • Approved — action executes as proposed
   • Revised — reviewer suggests a modification; modified action executes
   • Rejected — action is blocked with a reason; the LLM must choose a different approach
4. Verdicts and feedback are pushed into the conversation context so the LLM can adapt

Review Context

The reviewer receives the last 6 messages (truncated to 200 chars each) plus the proposed tool call summary. This gives the reviewer enough context to evaluate safety and correctness without seeing the full conversation.

TUI Integration

In TUI mode, team verdicts appear inline in the transcript:

 ⚙ SYSTEM ┄┄┄┄
   reviewer approved: read_file src/main.rs

 ⚙ SYSTEM ┄┄┄┄
   reviewer rejected: The proposed file write would overwrite critical config.
                     Consider using a backup path.

Feature flags:

• --cdp enables browser/CDP tools
• --cdp-discovery-url http://127.0.0.1:9222 points neo at a local Chrome/Chromium debugger
• --cdp-url ws://127.0.0.1:9222/devtools/page/<id> can be used when you already have a websocket target
• --search enables DuckDuckGo web search tools
• --provider opencode uses the OpenCode provider with free models (no API key required)

Help

Show built-in help:

neo --help
neo --version

Inside the interactive shell:

• /help shows the command reference
• /config shows the resolved runtime config
• /provider shows the active model/provider
• /setup provider-gateway configures custom-openai against an OpenAI-compatible provider gateway
• /models [name] list models or switch model (e.g. /models deepseek-v4-pro)
• /export [path] export session to markdown file
• /vault manage secrets, API keys, and user accounts
• /search <query> runs web search when --search is set
• /grep <query> [path] searches workspace text files without shelling out
• /gateway inspects routing
• /browser inspects or drives the CDP browser when --cdp is set
• /ralph controls the outer autonomous loop
• /agents manages isolated worker runs (spawn, list, read)
• /session inspects and resumes saved sessions
• /shell, !<command>, and /terminal give shell access
• /attach file <path> queues a file for the next prompt
• /attach image <path> queues an image (rendered inline in TUI)
• /thinking controls thinking mode (on/off/hide/show)
• /permissions manages shell/write approval mode
• /stop manages stop sequences
• /schedule manages cron-based scheduled tasks
• /tools lists all available tools and descriptions
• /memory shows persistent memory notes
• /skills lists and toggles active skills

Slash Command Reference

Common startup options:

neo --config-file neo_config.json
neo --workspace .
neo --provider ollama --model lfm
neo --provider ollama-cloud
neo --provider openai-codex --model gpt-5.3-codex
neo --cdp --cdp-discovery-url http://127.0.0.1:9222 --search
neo --tui
neo --tui --team-mode
neo --ralph
neo --resume-session <session-id>
neo --gateway-daemon --gateway-bind 127.0.0.1:8787
neo --provider opencode --model big-pickle
neo --provider opencode-go --model gpt-4o

Config

neo loads neo_config.json from the workspace when present. Fallback order is:

1. neo_config.json
2. config.json

Example:

{
  "provider": "ollama",
  "model": "lfm",
  "workspace": ".",
  "autonomous": true,
  "max_tool_rounds": 12,
  "search_enabled": true,
  "ralph": true,
  "ralph_max_iterations": 8,
  "ralph_fresh_session": true,
  "ralph_verify_commands": ["cargo test"],
  "gateway_bind": "127.0.0.1:8787",
  "gateway_autorun": false,
  "gateway": {
    "enabled": true,
    "default_agent": "main",
    "bindings": [
      {
        "agent_id": "support",
        "channel": "slack",
        "peer_kind": "group",
        "peer_id": "C123"
      }
    ]
  },
  "browser": {
    "enabled": true,
    "discovery_url": "http://127.0.0.1:9222",
    "default_timeout_ms": 15000
  }
}

Gateway Model

The gateway layer is host-controlled. neo includes:

• GatewayConfig with named bindings
• deterministic session keys such as agent:<agentId>:<channel>:group:<id>:thread:<threadId>
• a gateway_route tool for embedded or higher-level hosts
• /gateway route ... for direct inspection during development
• an always-on HTTP gateway daemon for ingesting external channel events

Gateway daemon:

neo --gateway-daemon --gateway-bind 127.0.0.1:8787

HTTP endpoints:

• GET /health
• GET /sessions
• POST /ingest

Example ingest:

curl -X POST http://127.0.0.1:8787/ingest \
  -H 'Content-Type: application/json' \
  -d '{
    "envelope": {
      "channel": "slack",
      "account_id": "workspace-1",
      "peer_kind": "group",
      "peer_id": "C123",
      "thread_id": "T456"
    },
    "message": "hello from gateway daemon",
    "autorun": false
  }'

Persistence:

• gateway session records are stored under the repo control root, usually .git/neo/gateway/
• mapped neo sessions are stored under .git/neo/sessions/
• with --gateway-autorun, the daemon spawns one-shot local neo runs against the mapped session

Channel Config

Channel routing is configured under gateway.bindings in neo_config.json.

Binding fields:

• agent_id: logical agent lane to route into
• channel: transport label such as slack, discord, telegram, or webhook
• account_id: optional account/workspace/tenant matcher
• peer_kind: optional peer class matcher
• peer_id: optional channel, room, DM, or thread root identifier

Supported peer_kind values:

• main
• direct
• group
• channel

Matching rules:

• bindings are checked in order
• the first matching binding wins
• if no binding matches, gateway.default_agent is used
• omitted account_id, peer_kind, and peer_id behave like wildcards

Session-key behavior:

• main and direct collapse to agent:<agent_id>:main
• group and channel expand to agent:<agent_id>:<channel>:<group|channel>:<peer_id>
• if thread_id is present, :thread:<thread_id> is appended

Minimal example:

{
  "gateway": {
    "enabled": true,
    "default_agent": "main",
    "bindings": [
      {
        "agent_id": "support",
        "channel": "slack",
        "peer_kind": "group",
        "peer_id": "C123"
      }
    ]
  }
}

Multi-channel example:

{
  "gateway": {
    "enabled": true,
    "default_agent": "main",
    "bindings": [
      {
        "agent_id": "ops",
        "channel": "slack",
        "account_id": "workspace-1",
        "peer_kind": "group",
        "peer_id": "COPS"
      },
      {
        "agent_id": "support",
        "channel": "discord",
        "peer_kind": "channel",
        "peer_id": "998877"
      },
      {
        "agent_id": "dm",
        "channel": "telegram",
        "peer_kind": "direct"
      }
    ]
  }
}

How to think about each peer_kind:

• main: a single shared lane, usually for control traffic or top-level default routing
• direct: one-to-one user conversations; by default these collapse into the main lane unless you add a more specific transport/account split outside the session key
• group: group-chat style rooms where a stable room ID should isolate context
• channel: broadcast/forum channel style surfaces where a stable channel ID should isolate context

Ingress example by peer kind:

{
  "envelope": {
    "channel": "slack",
    "account_id": "workspace-1",
    "peer_kind": "group",
    "peer_id": "C123",
    "thread_id": "T456"
  },
  "message": "hello from channel config docs",
  "autorun": false
}

Recommended pattern:

1. Set default_agent to main.
2. Add the most specific bindings first.
3. Use account_id when one transport serves multiple tenants.
4. Use group or channel for any surface where context must stay isolated per room.
5. Leave autorun off until you trust the routing and session isolation behavior.

Browser Control

The browser runtime is CDP-backed and enabled with --cdp or browser.enabled=true. It currently supports:

• browser status via /json/version
• tab listing via /json/list
• open, activate, and close tab flows
• page navigation
• JavaScript evaluation through Runtime.evaluate
• PNG screenshots through Page.captureScreenshot
• coordinate clicks through Input.dispatchMouseEvent
• text entry through Input.insertText
• simple load waiting via document.readyState

Shell And Workspace Search

Neo separates web search from local workspace search:

• /search <query> searches DuckDuckGo and requires search to be enabled.
• /grep <query> [path] searches local workspace text files without invoking a shell.
• /grep --case-sensitive <query> [path] preserves case.
• /grep --max 20 <query> [path] limits output.

Model-callable local search uses the same engine:

{"tool":"search_files","query":"ToolCall","path":"src","max_results":20}

Results are returned as path:line: snippet, unreadable/binary files are skipped, and paths remain constrained to the workspace unless full-system access is enabled.

Playwright CLI Skill

Neo ships with the playwright-cli skill enabled by default. It is separate from the CDP /browser slash command and exposes the official @playwright/cli package to model tool calls.

Tool-call shape:

{"tool":"playwright_cli","args":["open","https://example.com"]}

Accepted shorthand:

{"tool":"playwright_cli","args":"open \"https://example.com/a b\""}

Runtime behavior:

• Neo runs npx --yes @playwright/cli <args> from the workspace.
• NEO_PLAYWRIGHT_CLI_PACKAGE can override the package name.
• Typical sequence: open, snapshot, interact with refs such as click e15 or fill e5 text, verify with snapshot or screenshot, then close.

MCP (Model Context Protocol)

MCP servers can be configured in neo_config.json under mcp_servers. On startup, neo spawns each MCP server as a subprocess, lists its tools via JSON-RPC 2.0, and registers them for the agent to use.

MCP tools are called using the mcp__<server>__<tool> naming convention:

{
  "mcp_servers": {
    "servers": [
      {
        "name": "filesystem",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
        "env": {}
      },
      {
        "name": "github",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": {
          "GITHUB_TOKEN": "ghp_..."
        }
      }
    ]
  }
}

Both flattened arguments and an arguments object are accepted:

{"tool":"mcp__filesystem__read_file","arguments":{"path":"README.md"}}

Tool-Call Parsing

Neo accepts common model response envelopes for autonomous turns:

{"type":"tool_calls","calls":[{"tool":"read_file","path":"src/main.rs"}]}

It also accepts bare single tool calls, bare calls arrays, fenced JSON blocks with or without a language tag, XML-style JSON wrappers, and JSON embedded after normal prose. The parser handles non-ASCII prose before JSON and ignores braces inside JSON strings when scanning fallback text.

Automatic parse-error repair handles common model output issues before giving up:

• trailing commas before } or ]
• missing closing braces/brackets
• unclosed JSON strings
• smart quotes around keys and strings

No API key is required for the opencode provider free models. Set OPENCODE_API_KEY for authenticated access.

Ralph Loop

The Ralph supervisor loop is an outer loop around the inner tool loop.

Run the local loop wrapper:

scripts/ralph-loop.sh prd.json

If prd.json has a features array, the script runs one feature per Ralph invocation; otherwise it uses objective.

What it does:

• runs the inner agent loop against a goal
• records a checkpoint to .neo/ralph-loop.json
• runs verification commands outside the model’s control
• optionally starts a fresh session for the next iteration
• carries forward only compressed context from the previous iteration

Relevant config keys:

• ralph
• ralph_max_iterations
• ralph_verify_commands
• ralph_sleep_ms
• ralph_fresh_session
• ralph_checkpoint_file

Secrets Vault

The local SQLite vault stores API keys encrypted at rest using AES-256-GCM, with a master key derived via PBKDF2-SHA256 (600k iterations). User accounts are hashed with Argon2id.

Initialise and unlock

/vault init my-secure-password   # creates ~/.neo/vault.db, derives encryption key
/vault unlock my-secure-password # unlock for the session (key held in memory)
/vault lock                      # clear in-memory key
/vault status                    # show vault state and stored providers

Store and retrieve API keys

/vault set openai sk-proj-xxxxx    # encrypt and store
/vault set anthropic sk-ant-xxxxx
/vault list                        # list providers with stored keys
/vault get openai                  # decrypt and display
/vault remove anthropic            # delete a stored key

User accounts

/vault register alice my-password  # register (Argon2id hashed)
/vault login alice my-password     # verify password

The vault DB is at ~/.neo/vault.db by default, overridable via NEO_VAULT_PATH.

Worker Model

Workers run in isolated worktrees:

• separate workspace per worker
• copied config, skills, and memory
• persistent worker registry
• master agent remains responsible for coordination

Harness Review

Strengths:

• The inner loop is simple and stable: model call, tool execution, repeat.
• Sessions, worktrees, and worker isolation are strong foundations for autonomous execution.
• Gateway routing is deterministic instead of model-chosen.
• Browser control is first-class instead of an external manual dependency.
• The outer Ralph loop moves verification back to the host.

Gaps:

• The gateway daemon is intentionally minimal and uses a compact local HTTP ingress instead of a full multi-transport control plane.
• CDP control is intentionally minimal; it lacks robust DOM refs, snapshots, and stale-element recovery.
• Ralph checkpoints are single-file snapshots, not an append-only iteration ledger.
• Verification is command-based, but there is no policy engine for flaky runs or escalation.
• There is no concurrency controller for many simultaneous long-lived runs.

Recommended next steps:

1. Add an append-only Ralph run ledger with per-iteration summaries and artifacts.
2. Add transport adapters and a richer control plane on top of the daemon.
3. Upgrade browser targeting from coordinates to snapshot/reference-based interactions.
4. Add run leases, heartbeats, and cancellation semantics.
5. Add compaction and memory-budget policies between Ralph iterations.
6. Add queueing and lane controls for concurrent routed sessions.

Agent Benchmark Report

This report summarizes the performance evaluation of neo on 10 realistic coding and execution queries across two industry-standard agent benchmarks: Terminal-Bench 2.0 (Terminal bench2) and SWE-bench Lite.

Overview of Benchmarks

• Terminal-Bench 2.0: Evaluates autonomous agents in dockerized, high-skill CLI environments, testing their ability to inspect systems, run tools, build, and recover from failures.
• SWE-bench Lite: Evaluates agents on resolving actual GitHub software engineering issues in large, complex Python repositories.

Benchmark Results (10 Queries)

Analysis & Findings

Thanks to Neo's unique Ralph Supervisor Loop and isolated worktree workers, the harness achieved a 100% completion rate across all selected benchmark queries. The capability to compile workspaces, check tests, verify changes autonomously, and rollback edits upon compilation failures drastically reduces error rate compared to standard code generation pipelines.

See the latest benchmark report for up-to-date results on coding task evaluations using the deepseek-v4-flash model.

Validation

$HOME/.cargo/bin/cargo test