Splice documentation

Splice is a local-first terminal agent for repository work. It can inspect code, edit files, run checks, and use your selected model provider.

Splice combines a chat-first TUI with a typed execution pipeline. The TUI helps you shape the work. The pipeline turns the approved request into checked stages.

Quick start

The npm package requires Node.js 24 or newer.

npm install -g @taf0711/splice
splice

The first launch opens provider setup. Enter a request in the TUI, or start a headless run:

splice exec "fix the test failure in ./pkg"

See Install Splice for release archives, source builds, and platform notes.

Choose a workflow

Shape a change in the TUI

Run splice to open the interactive interface. A new session starts in design mode.

1. Describe the change.
2. Use /crystallize to create a typed design plan.
3. Review the critique and revise the plan if necessary.
4. Use /approve to start execution.

Use /exec <prompt> when you do not need a design conversation. The command starts the execution pipeline directly.

The TUI also provides provider and model selection, permission prompts, session resume, image input, themes, and transcript review.

Run one request from a script

splice exec "explain internal/agent/loop.go"
splice exec --use-spec "add rate limits to the API client"
splice exec --worktree "try the migration in isolation"
splice exec --worktree --merge-back "update the parser and merge the result"
splice exec --plan design-plan.json

splice exec supports text, JSON, and JSONL output. It also supports session resume, isolated worktrees, and explicit autonomy limits.

Run in CI

Use the Splice GitHub Action, or call splice exec from any job. Use stream JSON when another process must consume live events.

splice exec --output-format stream-json "run the repository checks"

How the pipeline works

Splice does not give one model turn every responsibility. The orchestrator owns the run and gives each stage only the data it needs.

request
  |
  v
classify -> typed plan -> focused context
                           |
                           v
                write -> analyze -> test -> verify
                           |
                           v
                  trajectory decision
                           |
             continue, recover, ask, or stop

The current classifier selects trivial, light, substantial, or architectural. The schema also retains standard for compatible saved plans.

Model-backed stages write code or tests. Local stages perform static checks, security checks, test execution, and acceptance verification. Each boundary uses validated Go data instead of an unstructured chat transcript.

The trajectory monitor compares completed passes. It detects repeated code state, oscillation, score regression, token limits, and confidence decline. The orchestrator can revise context, select an escalation model, restore a worktree snapshot, request a fresh analysis, ask the user, or stop.

Read Pipeline behavior for stage sets, success rules, recovery behavior, and current limits.

Safety and local data

Splice keeps the inherited Zero safety controls in every run.

• Workspace reads are available by default.
• Writes stay inside approved roots.
• Shell, network, destructive, and elevated actions pass through policy checks.
• Unsafe modes require an explicit flag.
• Worktrees reduce the effect of a failed change, but they are not sandboxes.
• Output surfaces redact known secret values.

Inspect the active policy before a sensitive run:

splice sandbox policy
splice sandbox grants list
splice exec --add-dir ../shared "update both repositories"

Sessions stay on the local machine. The optional splice-memd sidecar stores bounded project observations in a local SQLite database. Splice adds no required hosted coordinator and no product telemetry.

Read Security in Splice before you use external tools on a sensitive repository.

Providers and models

Splice supports hosted providers, local model servers, and compatible custom endpoints. Run setup to select a profile and model.

splice setup
splice providers list
splice models list
splice doctor

Provider keys can come from environment variables, the setup flow, or the local credential store. Splice also supports selected OAuth flows.

export OPENAI_API_KEY=...
export ANTHROPIC_API_KEY=...
export GEMINI_API_KEY=...

Local models can use Ollama or LM Studio. Pipeline stages that return typed data need a model with tool-call support. Splice reports invalid responses. It does not select another provider without your request.

Read Configuration and OAuth and provider login for supported setup paths.

Extensions and repository tools

Splice includes the Zero extension surfaces for interactive agent runs:

• MCP servers and tools
• local skills and plugins
• hooks and plugin tools
• named specialists
• session search and lineage
• repository maps and verification commands
• background jobs and editor protocols

The deterministic pipeline uses a smaller fixed tool set. It does not load every interactive extension into each stage. See Pipeline behavior for the boundary.

Command map

Read Command guide for the complete command groups. The live splice --help output remains the exact flag reference.

Documentation

• Documentation index
• Install Splice
• Configuration
• Command guide
• Pipeline behavior
• Stream-JSON protocol
• Update Splice
• Specialists
• GitHub Action
• Benchmarks and evaluations

For contributors

Splice is a Go project. The optional memory sidecar is a separate Go module.

make check
make test-memd
make test-cli-tui

Read CONTRIBUTING.md before you start work. The project uses an issue-first contribution policy.

Zero foundation

Splice is a fork of Zero, an MIT-licensed terminal code agent. Zero supplies the TUI, provider adapters, tool registry, sandbox, sessions, worktrees, and extension systems.

Splice adds the typed pipeline, design workflow, deterministic verification, trajectory control, and optional local memory. Upstream code retains its original copyright and license.

License

Splice is available under the MIT License.