Congratulations on installing OB-1. This manual helps you get the most out of it.

Why OB1?

OB1 is built to self-optimize and maximize autonomy. Our goal: show that OB1 built OB1. If it can scale a small team to reach Claude Code parity, it can scale the next 50 engineers in your org.

• •Multi-Model: Claude Opus 4.5, GPT-5.2, Gemini 3 Pro—use the best model for each task via OpenRouter.
• •Background Agents: Keep working while OB1 optimizes, tests, and researches in parallel.
• •Session Forking: Explore multiple approaches without losing your main thread.
• •Built-in Code Review: Dedicated review agents analyze security, correctness, and code quality.
• •Auto-Configuring Skills: Skills generate from your session history and codebase patterns.

Get Started

Install

Our recommended install method for macOS and Linux:

npm install -g @obl-hq/ob1

Configure

Add your API key to your shell profile:

export OBL_API_KEY="obl_..."

Run

cd your-project
ob1

You're ready to start using OB1.

Using OB1

Yolo Mode

Press Ctrl+Y to toggle yolo mode—OB1's full autonomy mode. When enabled, OB1 executes all tools without asking for confirmation: file edits, shell commands, everything.

• On: OB1 moves fast, no interruptions
• Off: You approve each tool call before it runs

Commands

OB1 includes slash commands for common workflows. Type / to see all available commands.

Core Commands

Session Management

Collaboration & Sharing

To clone a shared session: ob1 --clone <share-id>

Configuration

Tools & Extensions

How to Prompt

For the best results, be explicit with what you want. Instead of "can you do X?", try "do X."

• Keep it short, keep it focused. Break large tasks into smaller sub-tasks.
• Don't make the model guess. If you know which files to look at, say so.
• If you want planning without code, say: "Only plan. Do NOT write code."
• Use AGENTS.md files to guide OB1 on build commands and conventions.

AGENTS.md

OB1 looks in AGENTS.md files for guidance on codebase structure, build/test commands, and conventions.

Sessions & Forking

OB1 automatically saves your conversation history. You can reference previous sessions, fork from any point, and explore parallel approaches.

• Session history: Browse past sessions with /resume
• Forking: Use /fork to branch from any message and try alternate approaches
• Rewind: Use /rewind to go back to any point in the conversation
• Named sessions: Use /session name for easier identification

Finding Threads

OB1 can search through your past threads to find relevant conversations. Search by keyword, file path, or task using the thread tool.

# Search threads in current project
{"action": "list", "search": "auth refactor"}

# Search across ALL projects
{"action": "list", "scope": "all", "search": "database migration"}

# Get full content of a specific thread
{"action": "get", "thread_id": "3"}

OB1 uses these threads to maintain context across sessions. When you reference a previous task, OB1 can pull in relevant history automatically.

Mentioning Files

Type @ to search for and mention files in your prompts. This gives OB1 direct context about which files you want to work with.

• File mentions: @src/components/Button.tsx includes the file in context
• Glob patterns: @src/**/*.test.ts mentions multiple files
• In AGENTS.md: Use @docs/style.md to always include referenced files

Queueing Messages

You can queue messages to be sent to the agent once it ends its turn, without interrupting its current work.

• Queue a message: Press Cmd+Shift+Enter (macOS) or Ctrl+Shift+Enter (Windows/Linux) to queue instead of send immediately
• Multiple queued messages: Queue as many follow-up instructions as needed

This is useful when you think of additional requirements while OB1 is still working, or when you want to chain multiple tasks.

Shell Mode

Execute shell commands directly without leaving OB1. Type ! in an empty prompt to toggle shell mode.

• Toggle shell mode: Type ! in an empty prompt
• Run commands: Commands execute directly, output is added to context
• Focus toggle: Press Ctrl+F to switch between agent and shell input

Sharing & Collaboration

Share your OB1 conversations with teammates or the community. Shared sessions can be viewed on the web and cloned to continue the work.

• Create share link: /chat share-link generates a web URL for your conversation
• Clone a session: ob1 --clone <share-id> starts a new session from a shared one
• Export to file: /chat share conversation.md exports to markdown or JSON

Git Worktrees

OB1 has first-class support for git worktrees, enabling isolated workstreams without branch switching overhead.

# OB1 can create and manage worktrees
ob1 "create a worktree for the auth-refactor feature"

Tools & Subagents

Skills

Skills are packages of instructions that teach OB1 how to perform specific tasks. They auto-configure from your session history and codebase patterns.

Skills live in ~/.ob1/skills/ (personal) or .agents/skills/ (project).

Subagents

OB1 can spawn subagents for complex tasks that benefit from independent execution. Each subagent has its own context and tool access.

Subagents are useful for:

• Multi-step tasks that can be broken into independent parts
• Parallel work across different code areas
• Keeping the main thread's context clean

Background Agents

Unlike traditional tools that block your terminal, OB1 can run tasks in the background. Keep coding while OB1 optimizes, tests, and researches.

Background agents report findings to your /inbox, organized by priority.

MCP Servers

Extend OB1 with additional tools using MCP (Model Context Protocol) servers. Configure in ~/.ob1/mcp.json or bundle with skills.

{
  "linear": {
    "url": "https://mcp.linear.app/sse"
  }
}

Code Review

OB1 has built-in PR review capabilities via the pr-review-workflow skill. It auto-activates when you share a GitHub or Graphite PR URL.

Triggering Review

• Share a PR URL: https://github.com/org/repo/pull/123
• Ask to review: "review PR #123"
• Share a Graphite link: https://app.graphite.com/github/pr/...

Review Checklist

OB1 automatically evaluates PRs against:

• Scope check: Single logical change? Right size?
• Structure: Clear title, description explains WHY
• Security: No secrets, proper auth checks
• Conventions: Follows existing patterns

Multi-Round Reviews

OB1 supports iterative review cycles—structural issues first, then refinements, then edge cases and polish.

Configuration

OB1 can be configured through ~/.ob1/settings.json. All settings use the ob1. prefix.

Permissions

OB1 has a sophisticated permission system that controls which tools and commands can run without approval. Permissions use a priority-based rule system with three tiers: Admin > User > Default.

Approval Modes

Policy Decisions

Each tool invocation is checked against policy rules. A rule can result in:

• allow: Tool runs without prompting
• deny: Tool is blocked outright
• ask_user: User must confirm before tool runs

Built-in Allow List

These read-only tools are auto-approved by default:

glob, search_file_content, list_directory,
read_file, google_web_search

Folder Trust

Use /permissions trust [path] to manage which folders OB1 can operate in. Untrusted folders require additional confirmation.

Pricing

Early Access

OB1 is currently in early access. All features are available free during this period.

Check your usage with /stats.

Enterprise

For teams requiring SSO, advanced security, and dedicated support, contact team@openblocklabs.com.

Support

For help with OB1, join our Discord community or email team@openblocklabs.com.

To report bugs, use /bug in OB1—it automatically includes your session context.

Supported platforms: macOS, Linux, Windows (WSL recommended).