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

---

What It Does

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.

Project Type	What It Creates	Key Processes
SaaS/Coding	plan.md, design.md, tasks.md	daily-build, weekly-review
Company Ops	budget.md, stakeholders.md, kpis.md	daily-ops, weekly-review, monthly-retro
Research	experiments.md, pipeline.md, paper-outline.md	experiment-cycle, writing-cycle
Agency	clients/, resource-allocation.md	sprint-cycle, client-review
Open Source	api-surface.md, community.md	release-cycle, community-check
Content	content-calendar.md	editorial-calendar
Infrastructure	runbooks/	change-cycle, weekly-audit

Key Features

• 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

---

Quick Start

Install

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.

Usage

# 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

What Happens

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

---

The Core Loop

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.

---

Enforcement (Hooks)

Gate	Hook	Behavior
No code without plan	enforce-planning-gate.sh	BLOCKS (exit 2)
No code without [~] task	verify-plan-following.sh	BLOCKS (exit 2)
No stop with pending tasks	check-completion.sh	BLOCKS (exit 2)
No .env writes	protect-files.sh	BLOCKS (exit 2)
Auto-handoff at 50 calls	auto-handoff.sh	Mechanical write
Plan re-read at 20/40/60/80	tool-call-counter.sh	Warning
Dashboard sync reminder	dashboard-sync-reminder.sh	Warning
Next task surfacing	load-state.sh	Context injection

---

Self-Improvement

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

---

Hub (Multi-Machine)

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

---

Architecture

~/.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

---

Requirements

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

License

MIT