ratchet-cli

ratchet

Interactive AI agent CLI with multi-provider support, multi-agent orchestration, and a rich terminal UI.

Install

go install github.com/GoCodeAlone/ratchet-cli/cmd/ratchet@latest

Or download a binary from Releases. Release artifacts include Linux and macOS tar.gz archives and Windows zip archives for amd64 and arm64. Windows installer packages are not published yet.

Features

• Auto-daemon pattern: Single daemon process serves multiple terminal TUI clients via gRPC over Unix socket
• Multi-provider: Anthropic, OpenAI, Google Gemini, Ollama support
• Multi-agent: Orchestrate teams of agents with role definitions
• Workflow engine: Built on the GoCodeAlone/workflow engine
• Universal instruction files: Loads CLAUDE.md, AGENTS.md, .cursorrules, .windsurfrules, RATCHET.md
• Rich TUI: Bubbletea v2 with streaming tokens, tool call display, permission prompts

Usage

ratchet                     # Launch interactive TUI
ratchet "fix the bug"       # Implicit chat mode
ratchet chat "prompt"       # Explicit chat mode
ratchet sessions            # Manage sessions
ratchet sessions history ID # Show persisted message history
ratchet sessions clone ID   # Clone a session with full visible history
ratchet sessions fork ID --at MESSAGE_ID
                            # Fork a session through a specific message
ratchet sessions tree ID    # Show root/parent/fork lineage
ratchet sessions browse ID  # Browse branch tree interactively
ratchet sessions summary ID "short label"
                            # Update the branch summary shown in lineage views
ratchet sessions compactions ID
                            # Show compaction records and archive sessions
ratchet acp                 # Run ratchet as an ACP stdio agent
ratchet acp client exec --command ./agent "prompt"
                            # Run one prompt against an external ACP agent
ratchet acp client exec --command ./agent --session work --no-wait "prompt"
                            # Append an ACP client prompt to a local FIFO queue
ratchet acp client queue work --json
                            # Inspect queued ACP client prompts
ratchet acp client drain work --command ./agent --max 2
                            # Drain queued prompts through one ACP session
ratchet acp client watch work --command ./agent --stop-when-empty
                            # Explicit foreground auto-drain for queued ACP prompts
ratchet acp client sessions list
                            # List persisted ACP client sessions
ratchet acp client sessions show ID
                            # Show persisted ACP client session metadata
ratchet acp client sessions export ID --output session.archive.json
                            # Export a portable ratchet-cli archive v1 JSON file
ratchet acp client sessions import session.archive.json --session imported
                            # Import an archive as a new local ACP client session
ratchet acp client compare --command ./agent --command ./other-agent "prompt"
                            # Run one prompt serially across multiple ACP agents
ratchet acp client flow run flow.json --input-json '{"task":"x"}' --command ./agent
                            # Run a JSON v1 ACP/compute flow
ratchet acp client profiles list
                            # List local ACP launch profiles and plugin templates
ratchet acp client profiles add local --command ./agent --trust
                            # Save a reviewed reusable ACP launch profile
ratchet acp client status ID
                            # Show ACP client session status
ratchet acp client cancel ID
                            # Cancel an active or queued ACP client prompt
ratchet daemon status       # Check daemon
ratchet provider list       # List providers
ratchet team start "task"   # Start agent team
ratchet hooks list --cwd .  # Review lifecycle hooks before trusting them

In the TUI, press ctrl+b or submit /tree to open the in-place session branch browser. Use arrow keys or j/k to move, left/right or h/l to collapse and expand, Enter to switch to a branch, r to refresh, and Esc to return to chat. Switching through the tree or sidebar rebuilds chat for the selected branch before new sends are accepted.

The TUI trust commands are daemon-backed at runtime: /mode <mode> switches between conservative, permissive, locked, sandbox, and custom; /trust list shows effective daemon rules; /trust allow "pattern" [--scope scope] and /trust deny "pattern" [--scope scope] add runtime rules; /trust reset clears runtime slash-command rules and rebuilds from config defaults. These commands do not edit config files or delete persisted permission grants.

Persistent trust grants are explicit. Use ratchet trust persist allow|deny "pattern" [--scope scope] or /trust persist allow|deny "pattern" [--scope scope] to store durable grants in the daemon's local state database through workflow-plugin-agent/policy.PermissionStore. Use ratchet trust grants or /trust grants to list them, and ratchet trust revoke "pattern" [--scope scope] or /trust revoke "pattern" [--scope scope] to remove one. Treat grant listings as sensitive local policy metadata because patterns can reveal local paths, commands, or workflow conventions.

Lifecycle hooks are reviewable local command hooks. User hooks in ~/.ratchet/hooks.yaml remain trusted by default for compatibility; project hooks in .ratchet/hooks.yaml and plugin-contributed hooks are listed but skipped until their descriptor hash is trusted. Use ratchet hooks list --cwd . to review event, source, status, hash, and a truncated command preview, then ratchet hooks trust <hash> to enable that exact descriptor. ratchet hooks disable <hash> overrides trust, and changed project or plugin hook commands produce a new hash that must be reviewed again. This hook trust model is local and hash-based; managed hooks remain deferred.

ACP launch profiles are reviewed launch specs for explicit foreground ACP client commands. Use ratchet acp client profiles list, add, install, trust, and remove to manage local profile copies. Profiles store command, args, cwd, and env key names only, never secret values. Built-in ACP agents win over profile names, and profile names cannot shadow built-ins. Trusted profiles can be used with --agent <name> for exec, drain, watch, compare, and flow run; untrusted profiles are listed but refused at execution time. Plugin-distributed profile templates can be installed into the local profile store, then reviewed or trusted like local profiles. The TypeScript extension SDK remains deferred.

See docs/policy-matrix.md for the Policy Matrix covering static config trust rules, runtime trust rules, persistent trust grants, permission prompts, explicit ACP client watch/drain, partial sandbox/path/network controls, hook trust, ACP launch profiles, retro evidence, and deferred daemon background drain and extension SDK work.

The ACP client queue persists prompt text under the user's XDG state directory. Do not use --no-wait for prompts that should not be written to local disk. ratchet acp client watch is an explicit foreground worker: it drains queued prompts only while the operator-started command is running and still requires an explicit --command or --agent launch target. It is not a hidden daemon background drain. ACP client archives are explicit JSON exports and can contain prompt text, responses, summaries, and queue history. Treat exported archives as sensitive conversation data.

The v0.24.0 release line adds reviewable hook trust controls and ACP launch profiles on top of ACP client archive import/export, serial compare, and JSON v1 flow commands, while continuing to publish Windows amd64/arm64 zip artifacts alongside Linux and macOS archives.

ACP client archive v1 JSON is a ratchet-cli portable format with ACPX-shaped metadata, not a raw ACPX JSON-RPC event log. JSON v1 flows support acp and compute nodes, template prompts, shared session handles, and persisted run bundles. JSON v1 flows also support action nodes for runtime-owned local commands; action nodes require --allow shell, and node working directories outside the flow base require --allow outside-cwd. Action stdout/stderr in run bundles is sensitive local command output. ACPX TypeScript flow runtime compatibility remains deferred.

ACP Client Examples

# Export and import an ACP client session archive.
ratchet acp client sessions export work --output work.archive.json
ratchet acp client sessions import work.archive.json --session work-copy

# Compare two external ACP agents with one prompt.
ratchet acp client compare \
  --command ./agent-a \
  --command ./agent-b \
  "Summarize the current project risks"

# Run a JSON v1 ACP/compute/action flow.
cat > flow.json <<'JSON'
{
  "format_version": 1,
  "start_at": "prepare",
  "nodes": [
    {
      "id": "prepare",
      "type": "action",
      "command": "ratchet",
      "args": ["version"]
    },
    {
      "id": "draft",
      "type": "acp",
      "prompt": "Draft a brief answer for {{ .Input.topic }} after {{ .Outputs.prepare.stdout }}",
      "session": "shared"
    },
    {
      "id": "result",
      "type": "compute",
      "select": "draft"
    }
  ],
  "edges": [{"from": "prepare", "to": "draft"}, {"from": "draft", "to": "result"}]
}
JSON
ratchet acp client flow run flow.json \
  --input-json '{"topic":"release readiness"}' \
  --command ./agent \
  --allow shell \
  --json

# Explicitly drain queued prompts while this foreground command is running.
ratchet acp client watch work \
  --command ./agent \
  --stop-when-empty \
  --max-per-cycle 2

Harness Modes

See docs/harness-emulation.md for credential-free mock provider recipes, and docs/competitor-parity.md for the dated source-backed parity matrix. Policy boundaries for trust, permissions, queue drain, hooks, and sandbox follow-ups are in docs/policy-matrix.md.