Sober 工作流

Prerequisites

• OS: macOS or Linux. Windows users should use WSL.
• Agents: Claude Code or Codex CLI must be installed.
• Runtime: Node.js 18+

---

Where does it install?

Sober operates within two distinct, decoupled scopes:

• 🏠 Global Scope (~/) — created by sober setup or sober install
• ~/.sober: Canonical source of truth for Sober policies, hooks, and skills.
• ~/.claude & ~/.codex: Configuration and rules safely merged with your existing runtime settings.
• 📁 Local Scope (./) — created by sober template
• [project]/AGENTS.md: The project-specific policy spine governing the agent.
• [project]/HANDOFF.md: Local session memory ensuring seamless task handoffs between invocations.

---

make exactly one change to your setup

/measure after ```

Key metrics to watch:

• Files read per task
• Output tokens
• Peak context fill
• Retry rate

If any metric gets worse, roll back.

---

What gets installed

┌──────────────────────────────────────────────────────────────┐
│                         Sober                                │
│                    shared home: ~/.sober                     │
│                                                              │
│   ┌──────────────┬──────────────┬────────────────────────┐   │
│   │   AGENTS.md  │   skills/    │        scripts/        │   │
│   │ shared rules │ tool habits  │ safety + handoff hooks │   │
│   └──────────────┴──────────────┴────────────────────────┘   │
│             ↓              ↓                  ↓              │
│        Claude Code      Codex CLI        project template    │
│        ~/.claude        ~/.codex         AGENTS/HANDOFF      │
│             ↓              ↓                  ↓              │
│      merged settings   hooks + rules     local overrides     │
└──────────────────────────────────────────────────────────────┘

Installed file tree

```text ~/.sober/AGENTS.md # shared policy source ~/.sober/commands/.md # Sober-owned Claude slash commands ~/.sober/rules/.md # Sober-owned Claude rules ~/.sober/skills/<skill>/SKILL.md # one copy of each skill ~/.sober/scripts/ # local hook and verification scripts ~/.sober/codex-rules/*.rules # installed copy of .sober/codex/rules

Quick Start

Usage Guide

Optional Tools

Sober works without these tools. Some of them reduce files read, output volume, or retry loops for specific tasks.

sober setup interactively offers the core search/edit toolkit — ripgrep, ast-grep, Probe — plus Context7 setup.

Conditional tools such as GitNexus, Serena, and mgrep are reported by sober doctor and should be added manually only when they pay for themselves.

Core optional toolkit

These tools pay off in most projects. They make Sober's default loop — search, minimal edit, verify, brief report — cheaper and more reliable.

Internal Structure & Reference

3-Step Developer Workflow

Establish calm working habits for your AI agent in three simple steps.

#### Step 1: Global Installation & Setup Choose the installation path that best fits your development environment:

##### Option A: Interactive Installer (Highly Recommended for First-Time Setup) Deploys Sober rules/hooks and interactively checks/guides you through installing optional deterministic tools (jq, ripgrep, ast-grep, Probe, and Context7).

npm install -g getsober@latest
sober setup

##### Option B: Core Configuration Only (Silent Update) Only deploys Sober's core policy and skill files to ~/.sober and links them to the AI runtimes. (Best for updates or if you already have the required tools installed).

npm install -g getsober@latest
sober install

---

#### Step 2: Project Integration Navigate to your project root and generate the local policy contract (AGENTS.md) and session memory (HANDOFF.md).

cd your-project
sober template .  # Generates local agent contract & handoff templates
claude            # or: codex (run your agent as usual)

[!TIP] Prompt your agent with clear, scoped requests to see Sober in action:

> Fix the login timeout bug.
> Find the right lines first, make the smallest safe change, and verify with tests.
> 

---

#### Step 3: Diagnostics & Maintenance Use these commands to diagnose the toolchain status or safely remove configurations:

- Run Diagnostics: Checks the status of hooks, skills, dependencies, and optional tools.

  sober doctor
  

  sober uninstall
  

---

Troubleshooting

---