Quick Start

This guide takes you from a clean install to a working SOBA v0.6.8 workflow. It is the practical path: install, verify the provider, start the TUI, run a bounded task, inspect evidence proof receipts, save Project Memory, connect MCP, use skills, and finish with real checks.

1. Install and check

With npm:

npm install -g soba-agent

The npm package includes a pinned Bun runtime dependency, so users do not need to install Bun separately before running soba.

With Bun:

bun add -g soba-agent

Use the Bun install path when Bun is already part of your toolchain and you want Bun to manage the global package.

Standalone binaries for macOS and Linux are attached to GitHub Releases. For normal use, prefer npm or Bun; use a binary when you do not want a global package install.

Check the CLI:

soba --version
soba --help
soba init --check

From source, use:

git clone <repo-url> soba-agent
cd soba-agent
bun install
bun run build
bun run src/cli.ts --version

2. Configure a provider

List configured providers:

soba provider list

Run a minimal one-shot check:

soba --no-session --max-agent-iterations 1 "Answer with one word: ok"

Add a local OpenAI-compatible provider:

soba provider add ollama \
  --base-url http://localhost:11434/v1 \
  --model llama3.1="Llama 3.1",8192,2048 \
  --set-active

For local models, start with a modest context and output size. 8192,2048 is much gentler on a laptop than a 128k context. Raise it later only if the model and hardware handle it comfortably.

See Providers and models.

3. Start the TUI

soba -i --lang en --theme graphite

Useful first commands:

/session
/sessions list
/budget
/permissions ask
/auto-compact on
/plan on

For a disposable repository, you can switch to repo-scoped permissions:

/permissions repo

repo suppresses prompts only for dangerous operations that stay inside the current repository. Use /permissions full only when you want to trust all dangerous operations for the current session, including external commands.

Use /plan on when you want a read-only implementation plan before making changes. See Plan and goal modes.

4. Run the first bounded task

Example prompt:

Inspect this project.
Read package.json and the src/tests layout first.
Then propose a short plan.
If edits are needed, keep them inside the plan and run a targeted test.
Do not create a git commit.

Use direct shell ! for quick commands you run yourself:

!git status --short
!git diff --stat
!bun test

Use !! when the command output should stay out of the transcript:

!!bun run build

If you want the agent to analyze command output, ask it in a normal message so it can call the bash tool itself.

5. Continue sessions

soba -i
soba -c -i
soba -r
soba -s <SESSION_ID> "Continue the task"

Inside the TUI:

/session
/sessions list
/budget

For throwaway prompts:

soba --no-session "One-off question"

6. Manage long context

Turn proactive compaction on:

/auto-compact on

Create a manual compact checkpoint:

/compact Preserve the goal, decisions, changed files, checks, risks, and next step.

Inspect or rewind checkpoints:

/capsule
/capsule CHECKPOINT_ID
/rewind
/rewind CHECKPOINT_ID

7. Save Project Memory

Project Memory stores durable project facts in .soba/memory/ and makes them available across sessions.

Ask SOBA to write durable facts with memory source receipts:

Update Project Memory:
- architecture: core modules and data flow;
- conventions: Bun only, strict TypeScript, tests with bun test;
- known-errors: recurring failures and verification commands;
- dependencies: important runtime and dev dependencies.

Use project memory tools. Include source.file, source.lines, source.lastVerified, source.confidence, and staleIfFilesChange when a source can be verified.
Do not store secrets.

Check Project Memory doctor and Memory health commands:

soba memory doctor
soba memory doctor --format json
soba memory stale
soba memory verify
soba memory explain "provider registry"

Use soba memory explain for Memory receipt explanations: it shows matching capsules, source receipts, relevance score, and doctor issues.

See Project Memory.

8. Connect MCP tools

MCP servers are configured in .soba/mcp.json:

/mcp status
/mcp start <server>
/mcp reload
/mcp status

SOBA supports local stdio servers and remote streamableHttp endpoints. Remote auth should use bearerEnv or apiKeyEnv; OAuth commands require an auth controller for that provider:

/mcp auth login <server>
/mcp auth status <server>

MCP tools appear in the agent tool registry as:

mcp_<server-id>_<tool-name>

9. Use skills

List skills:

/skill list

Activate a skill:

/skill:commit-message Suggest a conventional commit message for staged changes.

Project skills require trust:

/project-trust status
/project-trust approve

For reusable skills, run the Skill eval bench and trace loop:

/skill eval <name>
/skill bench <name>
/skill trace <name>

See Skills.

10. Verify proof receipts

After non-trivial work, inspect the local proof trail:

soba prove --last
soba verify --last
soba explain-claim "No test regressions detected"

Evidence proof receipts live in .soba/evidence/*.soba-proof.json. A good receipt shows changed files, checks, proof claim mapping, risks, and proof permission receipts. If a claim is not supported by evidence, it should stay visibly unverified. Use soba explain-claim --proof .soba/evidence/<id>.soba-proof.json for Proof claim explanations from a specific receipt.

See Proof receipts.

11. Minimal finish gate

For a Bun/TypeScript project:

!bun test
!bun run build
!bunx tsc --noEmit
!git diff --check
!git status --short

For SOBA itself, also run:

!bun run lint

12. Next steps