SynapsCLI: Instructions file for Codex

AGENTS.md — SynapsCLI Developer & Agent Guide

This is the onboarding doc for any agent (Cursor, Aider, or SynapsCLI itself) touching this codebase. Read this first. If you only read one file, read this one.

SynapsCLI is a terminal-native AI agent runtime written in Rust. ~210K LOC across the workspace (counts drift — verify with find src crates -name '*.rs' -not -path '*/target/*' | xargs wc -l). Cargo workspace with three library crates + a root binary crate:

• synaps-core (crates/agent-core/) — config, session, auth, credential broker, models, memory, orchestration policy, prompt manifests, pricing, protocol primitives
• synaps-engine (crates/agent-engine/) — runtime, provider catalogs, credential routing, tools, memory tools, reactive subagent lifecycle, MCP, skills, events, extensions, sidecar, watcher
• synaps-tui (crates/agent-tui/) — the ratatui TUI
• synaps (src/main.rs) — the binary; CLI dispatch

Each crate has extern crate self as synaps_cli; and re-exports its dependencies, so internal synaps_cli:: paths still resolve for contributors navigating older references. Talks to Anthropic, OpenAI Codex, xAI, GitHub Copilot, Google Gemini, Azure OpenAI, Amazon Bedrock, Google Vertex AI, and Kimi natively, plus any OpenAI-compatible provider (Groq, Cerebras, NVIDIA, OpenRouter, local Ollama, etc.) via the built-in provider engine. Streams SSE, dispatches tools, renders a TUI.

Build & Test

cargo build --release                    # full release build (lto, single codegen unit, strip)
cargo build                              # dev build — faster compile, slower runtime
cargo test --workspace                   # all crates + integration tests
cargo test -p synaps-engine              # single crate
cargo test -p synaps-engine -- --test-threads=1  # required for PTY tests (TTY fd contention)
cargo test --test extensions_e2e         # end-to-end with real extension process
cargo clippy --workspace --all-targets --locked -- -D warnings  # linting (CI gate)