Best Agent

Autonomous AI agent that does ANY task a human can do on a computer. Code, run companies, conduct research, create content, manage projects. Self-improving. Never stops.

curl -fsSL https://raw.githubusercontent.com/fainir/best-agent/main/install.sh | bash

Best Agent wraps Claude Code with mechanical enforcement, self-improvement, and project management that makes it truly autonomous. It handles 7 project types out of the box.

• 30 hooks — Mechanical enforcement (exit 2 blocks). Can't code without plan. Can't stop with pending tasks. Can't commit secrets.
• 96+ skills — /init-project, /company, /research, /harness, /deploy, /security-audit, and 90 more
• Self-improvement loop — Karpathy-pattern: run evals → analyze failures → fix rules → re-eval → keep/revert
• Auto-handoff — Writes .claude/handoff.md mechanically at 50 tool calls and on context compaction
• Never-stop outer loop — Restarts Claude with fresh context, circuit breaker after 5 failures
• 11 dashboards — Board, timeline, metrics, calendar, process, architecture — all interactive HTML
• Hub — Multi-machine orchestration via WebSocket, goal decomposition, skill-based routing

curl -fsSL https://raw.githubusercontent.com/fainir/best-agent/main/install.sh | bash

This clones the repo, copies hooks/rules/skills to ~/.claude/, and links the CLI tools.

# Interactive mode — full autonomy, zero approval prompts
cloudbot-harness

# Or use the best-agent CLI
best-agent                    # Interactive mode
best-agent init               # Initialize project files
best-agent run "build a blog" # Never-stop loop mode
best-agent process            # Run overdue processes
best-agent ops                # Company operations loop
best-agent research           # Research experiment loop
best-agent eval               # Run eval suite
best-agent improve            # Self-improvement loop
best-agent status             # Project status

When you enter any git project, the agent:

1. Detects project type (SaaS, company, research, etc.)
2. Creates plan.md, strategy.md, design.md, tasks.md, knowledge.md, progress.md
3. Creates type-specific files (budget.md for company, experiments.md for research)
4. Sets up Process Maker with recurring workflows
5. Starts working through the plan, marking [~] → [x] as tasks complete
6. Writes handoff.md before context limits for seamless cross-session continuity

1. Read .claude/plan.md → find next [ ] task
2. Mark [~] → do the work → verify → mark [x]
3. Update tasks.md + progress.md
4. Go to 1. NEVER STOP.

Hooks enforce this mechanically. The agent cannot write code without a plan, cannot skip [~] marking, and cannot stop with pending tasks.

The system improves itself continuously using the Karpathy/AutoResearch pattern:

1. Run eval suite (150+ tasks)
2. Group failures by ROOT CAUSE
3. Propose ONE change (rules, hooks, skills, prompts)
4. Overfitting test: "Would this help even if the failing task disappeared?"
5. Commit → re-eval → keep if improved, revert if not
6. Log to results.tsv
7. Repeat forever

Run it: best-agent improve

The Hub connects multiple machines via WebSocket for orchestrated work:

Browser (any device)
    ↕ WebSocket (JWT auth)
Hub Server (Express + SQLite, port 3141)
    ↕ WebSocket (machine token)
Daemon (spawns Claude processes, PTY terminals, screen capture)

Features: goal decomposition, skill-based task routing, dynamic company engine, real-time dashboards.

cd hub && npm install && npm start  # Server
HUB_URL=ws://server:3141 npm run daemon  # Each machine

~/.claude/
├── CLAUDE.md .............. 47 lines — identity + work loop
├── settings.json .......... Permissions + 30 hook registrations
├── hooks/ ................. 30 bash scripts (enforcement + context)
├── rules/ ................. 13 rule files (1,040 lines total)
├── skills/ ................ 96+ slash commands
├── config/
│   └── bypass-permissions.json  # Zero-prompt mode for cloudbot-harness
└── projects/{hash}/
    └── memory/ ............ Auto-memory per project

Per-project (auto-created):

.claude/
├── plan.md ................ Source of truth (tasks + phases + DoD)
├── tasks.md ............... Active board
├── strategy.md ............ Vision + goals + constraints
├── design.md .............. Architecture + data model
├── knowledge.md ........... Stack info + gotchas
├── progress.md ............ Status report
├── process-maker.json ..... Recurring workflows
├── process-state.json ..... Runtime state
├── handoff.md ............. Auto-generated cross-session context
├── learnings.md ........... Long-term project memory
├── kb/ .................... Knowledge base wiki
└── *.html ................. Interactive dashboards

• Claude Code CLI (Max/Team/Enterprise subscription)
• macOS or Linux (Windows via WSL)
• Git, Node.js 18+

MIT