Highlights

• One production agent harness with a raw JSON-header + heredoc operation protocol.
• Configurable Flash and Pro OpenRouter model tiers.
• Optional image model; clear it to send images directly to the selected main model.
• Real plan and heavy-plan modes: read-only research → plan panel → approve, revise, or reject → implementation.
• Persistent architecture baseline and checklist for multi-deliverable work.
• Internal searchable engineering wiki with 30+ practical topics.
• Convergence guards for repeated builds, verification, exact-edit failures, path mismatch, cache misuse, and Prisma repair loops.
• Streaming reasoning, operation previews, file diffs, command output, grouped activity, and task progress.
• Append-only workspace-local JSONL sessions with automatic model-context compaction.
• Lazy transcript history: 100 visible turns per page with bounded rendered pages.
• OpenRouter key stored in VS Code SecretStorage.

Requirements

• VS Code 1.90.0 or newer.
• An OpenRouter API key.
• A workspace folder for filesystem/session features.
• Node.js only when developing or packaging Scarf itself.

Install

From VSIX

code --install-extension scarf-0.1.0.vsix

Or open Extensions → … → Install from VSIX….

Build from source

git clone https://github.com/t-of-u/Scarf.git
cd Scarf
npm install
npm run typecheck
npm run vsix
code --install-extension scarf-0.1.0.vsix

Press F5 from the repository to run an Extension Development Host. Use npm run watch while developing.

First run

1. Open Scarf from the Activity Bar or run Scarf: Open Chat.
2. Run Scarf: Set OpenRouter Key or /set-key.
3. Configure Flash, Pro, and Image model IDs if the defaults are unavailable on your OpenRouter account.
4. Choose an approval mode and test policy.
5. Describe the outcome you want.

To place Scarf on the right: Command Palette → View: Move View → Scarf Agent → Secondary Side Bar.

Execution modes

The plan panel supports Approve & implement, Approve & audit, Approve & auto, Request changes with comments, and Reject. Before approval, mutation and completion operations are runtime-blocked.

Models and media

Scarf exposes two main-model tiers:

• flash: fast/default lane.
• pro: stronger reasoning lane.

Both are configurable OpenRouter model IDs. The image model describes images/screenshots to the main model. When scarf.imageModel is empty, raw image attachments are sent directly to the main model instead. Documents are extracted locally where supported: PDF, Word, spreadsheets, and text; audio/video use a configured capable media model.

Settings

Slash commands

Use / in the composer to view the current command catalog. Common commands include:

• /set-key, /clear-key
• /model flash|pro
• /mode destructive|all|none|plan|heavy-plan
• /tests ask|run|skip
• /compact, /clear, /new, /sessions
• /plan to reopen the most recent plan
• skill commands such as /fe-react

Agent protocol

Scarf does not use a JSON array or native function-call XML. It accepts sequential JSON headers with raw heredoc bodies:

{"t":"fs","a":["ed"],"p":{"path":"src/app.ts","old":"const old = true;"}} <<EOF
const old = false;
EOF
{"t":"cmd","a":["sh"]} <<EOF
npm run typecheck
EOF

See PROTOCOL.md for filesystem, search, wiki, plan, checklist, capsule, and convergence behavior.

Architecture

src/
  extension.ts                 activation and commands
  config.ts                    settings/model resolution
  secrets.ts                   OpenRouter SecretStorage
  openrouter.ts                buffered + SSE API client
  session.ts                   append-only .scarf session store
  agent/
    loop.ts                    public single-harness facade
    v4test.ts                  production runtime and enforcement
    v4test-protocol.txt        authoritative model instructions
    stream.ts                  incremental operation parsing
    history.ts                 context routing/compaction
  handlers/                    fs, cmd, find, wiki, ask, capsule, output
  protocol/                    operation metadata and validation
  ui/                          chat webview and plan panel
  wiki/                        bundled engineering knowledge base
  capsules/                    reusable capability store

Sessions and context

Workspace-local state is stored under .scarf/ and ignored by Git:

.scarf/
  .gitignore
  config.json
  sessions/
    index.json
    <session-id>.jsonl
    <session-id>.state.json   # replaceable work checkpoint
  contexts/
    <session-id>/turn-*.json   # only when debugContext is enabled

Session writes are append-only during the production harness. Replaceable work state lives in a small sidecar checkpoint instead of being appended on every call. The UI initially renders the latest 100 visible turns and loads older/newer pages at scroll boundaries. The model sees a bounded recent window plus pinned goal, baseline, checklist, canonical root, and verified command profile rather than the entire visible transcript.

Development and packaging

Production packaging excludes source TypeScript, source maps, internal concept/design/product/protocol documents, test fixtures, .DS_Store, and source artwork. Client-side runtime JavaScript and bundled knowledge remain inspectable; never compile credentials or private server logic into an extension.

Documentation

• PRODUCT.md: product contract and boundaries.
• CONCEPT.md: architecture and operating model.
• DESIGN.md: brand, UI, accessibility, and scroll behavior.
• PROTOCOL.md: agent operation contract.
• docs/CI.md: Scarf corporate identity guide.

License

MIT © 2026 Tanawat Horsirimanon.