Larb

English

ไทย

English

ไทย

Appearance

Getting started ​

⚠️ Status: 0.1.0-alpha. Early, bring-your-own-key developers only. APIs and config may change. Larb runs autonomously and executes commands on your machine — skim the security model before relying on it.

1. Install ​

Larb needs Node.js ≥ 20. During the alpha it's published under the alpha tag, so install with @alpha:

bash
npm i -g @larb/cli@alpha
larb version

2. Choose a model (bring your own key) ​

Larb is model-agnostic — no provider is privileged. Pick one with kind in ~/.larb/config.toml and export that provider's API key. You own your keys (read from the environment, never from repo config) and your routing.

toml
# ~/.larb/config.toml
[provider]
kind = "openai"      # anthropic · openai · ollama · deepseek · gemini · groq ·
                     # mistral · xai · openrouter · together · perplexity

[provider.models]    # optional — omit to use the provider's defaults
orchestrator = "gpt-4o"        # strong model: plans & drives the loop
worker       = "gpt-4o-mini"   # cheap/fast model: subtasks & compaction
bash
export OPENAI_API_KEY=sk-...    # the env var for your chosen provider
larb providers                  # list providers + which keys are set

Prefer free / local? Set kind = "ollama" and run a local model — no key, no spend:

toml
[provider]
kind = "ollama"
[provider.models]
orchestrator = "llama3.1"

3. Your first session ​

Run bare larb in your project to open an interactive session — a conversation, not a one-shot command:

bash
cd your-project
larb

The first time, Larb asks for a trust decision (nothing is read-as-code or sent over the network before you decide). Then type tasks and follow-ups — the conversation carries across tasks, every file edit shows a diff for approval, and:

  • Esc interrupts a run at the next safe point so you can steer with a follow-up.
  • /plan <task> drafts a numbered plan first (no changes); review it, then type go to execute.
  • /cost shows session spend vs. your caps · /help lists everything.

Prefer one-shot commands? They still work:

bash
larb ask "What does this project do?"      # read-only
larb run "Add a --version flag to the CLI" # single governed task
larb run "fix the failing test" --yes      # headless (CI/scripts; needs prior
                                           # `larb trust --full`; add --json for
                                           # machine-readable output)

A task isn't "done" until your configured verification commands pass:

toml
verify = ["npm run -s typecheck", "npm test"]
# Optional: fast diagnostics after EVERY edit (errors surface immediately)
check = ["npm run -s typecheck"]

4. What to understand before relying on it ​

Larb is security-first — these are on by default:

  • Trust before anything — no executable config is read and no network call is made until you make a trust decision for a directory.
  • Capability permissions — writes, commands, network, and MCP calls are each approved (once / session / always / deny) and every grant is logged. See larb audit.
  • Hard spend caps — live token/$ accounting halts the agent before it overspends. Tune them under [limits].
  • Real sandboxed execution — commands run in a rootless container (docker/podman) with host secrets withheld and networking off by default; if no runtime is present it falls back to a reduced-isolation host subprocess and tells you which is active at the start of every run.

Read the full security model before unattended use.

5. Going further ​

  • Project instructions — drop an AGENTS.md in your repo to tell Larb your build/test commands and conventions (advisory; it can't override permissions).
  • Project memory — the agent can remember durable facts (build quirks, conventions) as inspectable markdown under .larb/memory, loaded into every future session.
  • External tools (MCP) — add [[mcp]] servers in your global config and inspect them with larb mcp / larb mcp probe. See the architecture.
  • Skills — install governed, signed extensions: larb skill <cmd>.
  • Durable runs — larb runs lists snapshots; larb resume continues an interrupted one (works headless too: larb resume --yes).
  • VS Code — an extension MVP over the larb bridge protocol lives in editors/vscode (build from source; marketplace listing planned).
  • Windows — supported and CI-verified (typecheck/tests/build/smoke on the ubuntu·macos·windows matrix).

Next ​