Prerequisites
Hector requires two things before you begin:
Go
Go 1.25 or later
Hector is written in Go. Install from
go.dev if you don't have it. Check with
go version.
AI
Claude CLI installed and authenticated
Hector invokes agents via Claude Code. Install from
docs.anthropic.com and authenticate.
claude must be on your PATH.
Installation
Install the hector binary with Go's package installer:
# Install from source
go install github.com/accuser/hector@latest
This installs the hector binary into $GOBIN (defaults to $GOPATH/bin). Make sure it's on your $PATH.
To build from source:
# Clone and build
git clone https://github.com/accuser/hector
cd hector
make build
Verify the installation:
hector --version
Initialise a project
Navigate to your project repository and run:
hector init
This creates a .hector/ directory containing:
.hector/
tasks.json
The task graph (your backlog)
.hector/
decisions.json
Architectural decisions and constraints
.hector/
security.json
Capability matrix and audit configuration
.hector/
roles/
Role definitions (customise or add your own)
.hector/
memory/
Episodic memory store (grows over time)
Commit .hector/ to your repository. The task graph, decisions, and role definitions should be version-controlled alongside your code.
Interactive TUI
Launch the terminal interface:
hector
The TUI opens a chat interface connected to the PM agent. Describe the work you want done in plain language — the PM agent will decompose it into structured tasks and add them to the project graph.
hector · interactive mode
PM agent ready. Describe the work you want to do.
you > Add rate limiting to the API. Each key should be limited to 1000 req/hour. Use Redis for shared state.
PM > I'll break that down into three tasks:
1. implement-redis-rate-limiter (engineer, priority 0.8)
2. integrate-rate-limiter-middleware (engineer, priority 0.7)
3. add-rate-limit-headers (engineer, priority 0.5)
Shall I add these to the backlog?
you > Yes. Also record that we're using Redis for rate limiting as a decision.
PM > 3 tasks added. Decision D-047 recorded.
Press Ctrl+T to toggle the task sidebar with live status of all tasks. Escalations appear in the chat — you can approve, reject, or redirect from the same interface.
Headless CLI
For automation and CI, run Hector without the TUI:
# Execute the next ready task
hector run
# Execute all ready tasks sequentially
hector run --loop
# Execute with limited parallelism
hector run --loop --concurrency 3
Both commands exit non-zero on failure, making them CI-friendly. Structured JSON output is available with --output json.
Writing effective tasks
Agents perform best when task descriptions are specific and scoped. A good task description includes what needs to be built, the context it lives in, and clear acceptance criteria.
❌ Too vague
"Add rate limiting"
✓ Clear and scoped
"Implement per-API-key rate limiting in internal/middleware/. Limit: 1000 requests per hour, using Redis for shared state (see decision D-047). Return 429 on limit exceeded with a Retry-After header. Tests must cover the exceeded-limit and reset-window scenarios."
Add a task via CLI:
hector task add \
--description "Implement per-API-key rate limiting..." \
--role engineer \
--priority 0.8
CLI command reference
$
hector init [--project-dir PATH]
Initialise a new project
$
hector run [--loop] [--concurrency N]
Execute tasks
$
hector status
Task counts by status and agent activity
$
hector task list [--status STATUS]
List tasks with optional status filter
$
hector task add --description "..." --role ROLE
Add a task to the backlog
$
hector decision list
Query the decision ledger
$
hector decision add --title "..." --body "..."
Record an architectural decision
$
hector memory list [--role ROLE]
Browse episodic memory records
$
hector security audit [--since DATE]
Review the structured audit log
$
hector retro [--task-id ID]
Generate a retrospective report
Recording decisions
Architectural decisions are included automatically in agent context. Record them early — before the agents start work on related tasks — so they appear in the right context from the start.
hector decision add \
--title "Use Redis for rate limiting state" \
--body "Rate limiting state is stored in Redis to support multi-instance deployments. Connection details are configured via REDIS_URL env var. See pkg/ratelimit/ for the client wrapper."
Decisions are stored in .hector/decisions.json and version-controlled. Every agent invocation related to in-scope tasks will see the relevant decisions in its context payload.
Inspecting memory
After a few completed tasks, you can inspect what the agents have learned:
# Browse all episodes
hector memory list
# Filter by agent role
hector memory list --role engineer
# Run a retrospective to surface patterns
hector retro
The Retrospective agent distils episodes into patterns automatically after each completed task. You can also trigger a manual retrospective at any time.
Want more?
Full documentation — including the role definition format, approval gate policy configuration, security setup, and the MCP server reference — is coming alongside early access.
Join the waitlist for early access →