Silvan

Silvan is an operator‑grade CLI for orchestrating resumable AI workflows around git repositories. It manages worktrees, plans and executes changes with guarded tools, verifies results, and drives PR/review loops with clear, deterministic gates.

Silvan is usable with or without external issue trackers. If GitHub/Linear are not configured, it still runs plan → implement → verify and stops before PR/review steps with a clear blocked reason.

Requirements

• Git >= 2.30
• Optional: GitHub token for PR/CI automation
• Optional: Linear token for ticket intake

Install

npm (recommended)

npm install -g silvan
silvan --help

Or run without a global install:

npx silvan --help

The npm wrapper downloads a platform‑specific binary on first run and caches it under the Silvan cache directory.

Direct binary download

Download the appropriate binary from GitHub Releases and run it directly:

• macOS: silvan-darwin-x64, silvan-darwin-arm64
• Linux: silvan-linux-x64, silvan-linux-arm64
• Windows: silvan-windows-x64.exe

If you download a Unix binary, make it executable:

chmod +x ./silvan-<platform>
./silvan-<platform> --help

Supported platforms:

• macOS (x64, arm64)
• Linux (x64, arm64)
• Windows (x64)

Troubleshooting:

• If binary download fails behind a proxy, set SILVAN_RELEASE_BASE to a reachable mirror URL.
• On macOS, Gatekeeper may require you to allow the binary in System Settings.

Publishing (maintainers)

• GitHub Releases and npm publish are automated on tag pushes (v*.*.*) using trusted publishing (OIDC).
• Configure the npm trusted publisher for stevekinney/silvan and .github/workflows/release.yaml.
• No NPM_TOKEN or NODE_AUTH_TOKEN is required once trusted publishing is enabled.
• Release with bun run release:patch, bun run release:minor, or bun run release:major.
• If the package is not yet bootstrapped on npm, do one interactive publish from a maintainer machine first.

Quick Start

# Initialize a baseline silvan.config.ts (auto-detects repo settings)
silvan init

# List worktrees
silvan tree list

# Start from a local task (no external tracker required)
silvan task start "Improve run status visibility"

# Start from a GitHub or Linear task
silvan task start GH-123
silvan task start ENG-456

# Launch the dashboard
silvan ui

Help Topics

Browse conceptual help in the CLI and drill into a topic when you need detail:

silvan help
silvan help worktrees
silvan help task-refs
silvan help convergence

CLI Output Conventions

Silvan output is designed to be scannable in terminals and scriptable in CI.

• Semantic colors: green success, yellow warning, red error, cyan running
• Section headers use consistent separators for fast scanning
• Commands end with a clear next steps block when there is a logical follow-on
• Non-TTY output is plain text (no ANSI colors)
• Use --json for machine-readable output (JSONL events with cli.result payloads)
• Use --quiet to suppress non-error output and --verbose for debug-level detail

What Silvan Does Today

Workflow overview

Default lifecycle:

1. task intake (local / GitHub / Linear)
2. plan (structured, validated)
3. implement (tool‑driven execution)
4. verify (configured commands)
5. local review gate (deterministic checks)
6. PR open + review loop (if GitHub configured)
7. converge (CI green + no unresolved review threads)

Silvan stores all artifacts and run state globally so runs can be resumed and inspected without repo‑local files.

Local tasks (no external tracker required)

silvan task start "Add fuzzy search to run list"

# With explicit fields
silvan task start --title "Add fuzzy search" --desc "Search the run list" \
  --ac "Matches partial strings" --ac "Highlights matched text"

# From a file
silvan task start --from-file task.md

Pre-answer clarifications or generate a plan without creating a worktree:

silvan task start GH-42 --answer auth-method=jwt
silvan task start GH-42 --plan-only

If GitHub is not configured, Silvan will run plan/implement/verify and stop before PR and review steps with a clear blocked reason.

Global State Model

Silvan stores all state outside the repo (no .gitignore required). Default locations:

• macOS: ~/Library/Application Support/silvan
• Linux: $XDG_DATA_HOME/silvan (or ~/.local/share/silvan)
• Windows: %APPDATA%\silvan

Per‑repo layout:

• repos/<repoId>/runs — run snapshots
• repos/<repoId>/audit — event audit logs (JSONL)
• repos/<repoId>/artifacts — run artifacts (plans, reports, summaries)
• repos/<repoId>/conversations — conversation snapshots
• repos/<repoId>/tasks — local task definitions
• cache/repos/<repoId> — rebuildable cache (AI results)

To keep state inside a repo, set state.mode = "repo" or pass --state-mode repo.

Operator Control and Convergence

Silvan derives a convergence status for each run and exposes operator controls to resume, override, or abort.

Commands:

• run status <runId> — show convergence status and next actions
• run explain <runId> — show blocking reasons and relevant artifacts
• run resume <runId> — resume using convergence rules
• run override <runId> <reason...> — record an explicit operator override
• run abort <runId> [reason] — abort a run and mark it canceled

“Blocked” means a deterministic gate failed and requires operator intent. “Waiting” means Silvan is waiting on CI or review state.

See docs/operator-control.md for details.

Local Review Gate

Before opening a PR or requesting review, Silvan runs a deterministic local gate (no model calls). It checks:

• diff size thresholds
• debug artifacts (console.log, debugger, TODO, FIXME)
• .env changes
• config/dependency changes
• git diff --check
• verification status (must pass before PR, if required)
• naming conventions

Configure under review.localGate:

review: {
  localGate: {
    enabled: true,
    runWhen: 'beforeReviewRequest',
    blockPrOnFail: true,
  },
}

Silvan can also run an optional AI reviewer after the local gate. It is enabled by default and can be disabled via review.aiReviewer.enabled.

To override a blocked run, use run override with a reason.

AI Architecture (precise, not magical)

Silvan separates AI work into two lanes:

• Cognition lane (homogenaize + conversationalist): read‑only, structured outputs for planning, classification, summaries, and recovery suggestions.
• Execution lane (Claude Agents SDK): tool‑using, side‑effectful execution (file edits, git ops, PR updates).

Key principles:

• Prompts are small and artifact‑first. Agents pull context via tools.
• Conversation snapshots are persisted and inspectable.
• Cognition outputs are cached by input digest to avoid repeated model calls.

Inspect conversation context:

• convo show <runId> — last N turns (default 20)
• convo export <runId> --format json|md — full snapshot

Configuration

Silvan loads configuration via cosmiconfig (silvan.config.* or a silvan key in package.json).

Supported filenames:

• silvan.config.ts
• silvan.config.js
• silvan.config.json
• silvan.config.yaml
• silvan.config.yml

Silvan searches upward from the current working directory and treats the nearest configuration file location as the project root for state, queue, and worktree operations.

If no config file is found, Silvan infers defaults from the git root, existing worktrees, optional worktrees.toml, and environment tokens. Run silvan init to write a silvan.config.ts based on those detections.

Example silvan.config.ts:

import { defineConfig } from 'silvan/config';

export default defineConfig({
  repo: {
    defaultBranch: 'main',
  },
  task: {
    providers: {
      enabled: ['local', 'linear', 'github'],
      default: 'local',
    },
  },
  github: {
    owner: 'acme',
    repo: 'my-repo',
    reviewers: ['octocat'],
    requestCopilot: true,
  },
  verify: {
    commands: [
      { name: 'lint', cmd: 'bun run lint' },
      { name: 'test', cmd: 'bun test' },
    ],
  },
  ai: {
    cache: { enabled: true },
    cognition: {
      provider: 'anthropic',
    },
  },
  review: {
    maxIterations: 3,
  },
  state: {
    mode: 'global',
  },
  ui: {
    worktrees: {
      staleAfterDays: 7,
    },
  },
});

Example silvan.config.json with schema:

{
  "$schema": "./node_modules/silvan/schemas/silvan.config.schema.json",
  "repo": { "defaultBranch": "main" }
}

Configuration precedence

1. CLI flags
2. Environment variables
3. silvan.config.*
4. Defaults

Environment variables

• GITHUB_TOKEN or GH_TOKEN: GitHub API access
• LINEAR_API_KEY: Linear task access
• ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY: cognition lane providers
• SILVAN_COGNITION_DEFAULTS=1: enable cognition-assisted defaults in init/quickstart
• SILVAN_COGNITION_MODEL_INIT_DEFAULTS: override the model used for init defaults
• SILVAN_STATE_MODE=global|repo: override state storage mode
• SILVAN_VERIFY_PORT: preferred port for verification commands (Silvan finds a free port when unset)
• SILVAN_VERIFY_BASE_URL: override base URL for verification commands
• Silvan auto-loads .env from the config directory or repo root and overrides existing env values.
• Verification commands receive SILVAN_VERIFY_PORT, SILVAN_VERIFY_BASE_URL, and PORT set to the resolved port.
• API keys are read at runtime from the environment and are never embedded in build output.

See silvan doctor for a full diagnostic report of effective configuration.

Commands (high‑level)

Worktrees

• tree list — list worktrees
• tree add <name> — create worktree + branch
• tree remove <name> — remove worktree (--force to override dirty check)
• tree clean — remove worktrees with merged PRs (--all to skip prompts)
• tree prune | tree lock | tree unlock | tree rebase — worktree maintenance

Agent workflows

• task start [task] — create worktree + generate plan (--answer, --plan-only)
• quickstart — guided setup + sample plan
• init — scaffold a baseline silvan.config.ts (--assist for cognition defaults)
• queue run — process queued task requests (--concurrency <n>, --continue-on-error)
• agent plan — generate a structured plan
• agent clarify — answer required questions and re‑plan
• agent run — execute plan (--dry-run, --apply, --dangerous)
• agent resume — generate recovery plan and execute next action

Runs + operator control

• run list / run inspect <runId> / run resume <runId>
• run status <runId> / run explain <runId> / run override <runId> <reason...> / run abort <runId>

Diagnostics

• doctor — validate git, config, tokens, and verification setup (--json, --network)

UI

• ui — live Ink dashboard (read‑only). Start new work via task start.

Safety Guarantees

• Worktrees are never removed without confirmation unless --yes is passed.
• Dirty worktrees are blocked unless --force is provided.
• All destructive actions are gated behind --apply and --dangerous.
• Steps are idempotent; resume does not repeat destructive operations.

Development

bun run dev

Testing

bun test

License

MIT