Quick Start

This guide gets you from a fresh checkout to a working SOBA v0.4.1 session. It focuses on the practical path: verify the provider, start the TUI, run a task, save project memory, and connect optional tools.

1. Install and check

With npm:

npm install -g soba-agent

With Bun:

bun add -g soba-agent

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

Check the CLI:

soba --version
soba --help

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 your model and hardware handle it comfortably.

See Providers and models for the full provider registry.

3. Start the TUI

soba -i --lang en --theme graphite

Useful first commands:

/session
/budget
/permissions ask
/auto-compact 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.

4. Run the first 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"

For throwaway prompts:

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

6. Use Project Memory, MCP, and skills

Project Memory stores durable project facts in .soba/memory/:

Update Project Memory with architecture, conventions, known errors, and dependencies.
Do not store secrets.

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

/mcp status
/mcp start <server>
/mcp auth status <server>

Skills are listed and activated from the TUI:

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

Next: CLI reference, Interface and commands, MCP servers, and Skills.