hawk

🦅 hawk

AI coding agent that reads, writes, and runs code in your terminal.

Built on eyrie (universal LLM provider), tok (tokenizer/compression), yaad (graph memory), and trace (session capture).

Install

# Homebrew (macOS/Linux)
brew install GrayCodeAI/tap/hawk

# Go
go install github.com/GrayCodeAI/hawk@latest

# Script (with checksum verification)
curl -fsSL https://raw.githubusercontent.com/GrayCodeAI/hawk/main/install.sh | sh

# From source
git clone https://github.com/GrayCodeAI/hawk && cd hawk && go install .

Quick Start

export ANTHROPIC_API_KEY=sk-ant-...
hawk

Model Agnostic

Hawk is fully model-agnostic. Model discovery, pricing, and routing are handled by eyrie. Hawk stores only provider, model, and API-key configuration.

# One-time setup
hawk config provider openai
hawk config key openai sk-...
hawk config model gpt-4o

# Per-run override
hawk --provider openai --model gpt-4o

# Non-interactive
hawk -p "summarize this repo" --provider anthropic --model claude-sonnet-4-20250514

In chat: /config provider <name>, /config key <provider> <api-key>, /model <name>.

Usage

hawk                          # Interactive REPL
hawk -p "explain this code"   # Print response and exit
hawk -m gpt-4o                # Specify model
hawk --provider openai        # Force provider
hawk -r abc123                # Resume session
hawk -c                       # Continue latest session
hawk --fork-session -r abc123 # Resume as new session
hawk --mcp "npx @mcp/server"  # Connect MCP server
hawk -p "fix tests" --allowed-tools "Bash(go test:*) Edit Read"
hawk -p "plan only" --permission-mode plan --tools "Read,Grep,Glob"
hawk exec "fix all tests"     # Non-interactive with full engine
hawk exec --auto full -o json "add error handling"
hawk exec --worktree "refactor auth module"
hawk exec --agent reviewer "review last commit"
hawk daemon start             # Background HTTP server
hawk daemon status            # Check if daemon running
hawk mission "add auth, rate limiting, and tests"
hawk mission --dry-run "decompose this into features"
hawk search "authentication"  # Search across all sessions
hawk agent list               # List custom personas
hawk agent create debugger    # Create new persona
hawk doctor                   # Run diagnostics
hawk config                   # Show effective settings
hawk sessions                 # List saved sessions
hawk tools                    # List built-in tools
hawk skills search api        # Search community skills
hawk skills install GrayCodeAI/hawk-skills go-review
hawk skills audit             # Security scan installed skills
hawk --auto-skill             # Auto-detect project, install matching skills

Skills

Hawk has a community skill registry — modular instruction packages that teach the agent specialized workflows.

# In the REPL
/skills                          # List installed skills
/skills search <query>           # Search community registry
/skills trending                 # Most popular skills
/skills install <owner/repo>     # Install from GitHub
/skills use <name>               # Activate for this session
/skills deactivate <name>        # Deactivate
/skills new <description>        # Create a new skill (LLM wizard)
/skills info <name>              # Show details
/skills remove <name>            # Uninstall
/skills feedback <name> <1-5>    # Rate a skill
/skills audit                    # Security scan for hidden Unicode threats
/skills publish <dir>            # Validate and publish

/learn                           # LLM-powered skill advisor
/learn deep                      # Advisor with source file analysis
/learn update                    # Re-analyze and flag outdated skills

# Non-interactive (CI/scripts)
hawk skills list
hawk skills search api --category engineering --json
hawk skills install GrayCodeAI/hawk-skills go-review --scope user
hawk skills audit --json
hawk --auto-skill

Skills are discovered from .hawk/skills/, .agents/skills/ (agentskills.io), ~/.hawk/skills/, and Claude/Codex directories for cross-agent compatibility. Install includes automatic security scanning — skills with dangerous hidden Unicode are sanitized on install.

Tools (40)

Plus any tools from connected MCP servers.

Slash Commands (91)

Core commands:

Run /help for the full list of 91 commands.

Providers

Hawk passes configured provider/model values to eyrie. API keys via hawk config key <provider> <api-key> or environment variables:

Architecture

Package Structure

cmd/          CLI commands and TUI (split: chat, commands, config, view, stream, print, welcome)
engine/       Agent loop, compaction, beliefs, backtracking, cascade router, context budget,
              reflection, self-review, session lifecycle (self-improvement loop)
tool/         40 built-in tools with safety layer (credentials, sensitive paths, backups)
config/       Settings loading, validation, budget, aliases, templates
session/      Session persistence (JSONL), WAL, snapshots, checkpoints, compression
prompt/       System prompt preamble (identity, safety)
prompts/      Modular prompt templates (role, tools, practices, communication, examples)
repomap/      Code intelligence (PageRank, BM25, TF-IDF, Shapley, import graph, change-set context)
memory/       Unified MemoryManager (auto, evolving, zenbrain, yaad bridge)
model/        Provider routing, health checking, roles (delegates catalog to eyrie)
mcp/          MCP client with buffered I/O and timeout
lsp/          LSP client with persistent reader
plugin/       Plugin runtime and smart skill auto-invocation
permissions/  Advanced permission system (auto-mode, classifier, killswitch)
hooks/        Event hook system with decision hooks
analytics/    Session traces, activity tracking, cost optimization, model cascade
trace/        Built-in tracer + optional OTel SDK (build tag)
sandbox/      Command isolation (namespace, docker, chroot, seatbelt, landlock, seccomp)
mission/      Multi-agent orchestration (parallel feature execution in worktrees)
daemon/       Background HTTP server (JSON + SSE streaming)
agents/       Custom agent persona loader (markdown + frontmatter)
parallel/     Worktree-based parallel task execution
retry/        Exponential backoff with jitter
circuit/      Circuit breaker (closed/open/half-open)
ratelimit/    Token bucket rate limiting

Zero CGO. Single static binary. Cross-compiled for linux/darwin/windows amd64/arm64.

Exec Mode

Run hawk non-interactively for scripting and CI:

hawk exec "fix all failing tests"
hawk exec --auto full "refactor to use context"
hawk exec --output-format json "list all TODO comments"
hawk exec --worktree "add rate limiting"           # isolated branch
hawk exec --agent reviewer "review the last 3 commits"
hawk exec -s exec-123456 "continue from last time" # resume session
echo "explain main.go" | hawk exec -               # stdin

Mission Mode

Decompose work into parallel features:

hawk mission "Add auth, rate limiting, and logging"
hawk mission --workers 6 --model claude-sonnet-4-6 "Refactor into microservices"
hawk mission --dry-run "What would this decompose into?"

Each feature runs in its own git worktree with full autonomy. Results are committed on separate branches.

Daemon

Background HTTP server for programmatic access:

hawk daemon start              # Start on port 4590
hawk daemon start --port 8080  # Custom port
hawk daemon status             # Check if running
hawk daemon stop               # Graceful shutdown

Endpoints:

• GET /v1/health — server status
• POST /v1/chat — send prompt, get response (JSON or SSE streaming)
• GET /v1/sessions — list active sessions

SSE streaming: set Accept: text/event-stream header.

Custom Agents

Define reusable personas in ~/.hawk/agents/:

hawk agent create reviewer -d "Security-focused code reviewer"
hawk agent list
hawk agent show reviewer
hawk exec --agent reviewer "check the auth module"

Agent files are markdown with YAML frontmatter:

---
name: reviewer
description: Security-focused code reviewer
model: claude-sonnet-4-6
---
You are a security expert. Focus on injection, auth bypass, and secrets.

AGENTS.md

Create an AGENTS.md in your project root for project-specific instructions (max 10KB). Any AI coding agent can read this — hawk, Claude Code, Cursor, Codex:

# My Project
- Go project using chi router
- Tests use testify
- Run tests: go test ./...

Hawk also reads AGENTS.md for backward compatibility.

Permission System

Hawk asks before running dangerous tools (Bash, Write, Edit, NotebookEdit):

⚠ Run: go test ./...  [y/n]

Features:

• Auto-mode: Learns from your decisions
• Command classifier: Safe/unsafe/unknown classification
• Bypass killswitch: Emergency disable for auto-mode
• Shadowed rule detection: Warns when rules conflict

hawk -p "review this repo" --permission-mode acceptEdits
hawk -p "fix lint" --allowed-tools "Bash(go test:*) Edit Read"
hawk -p "plan only" --permission-mode plan

MCP (Model Context Protocol)

hawk --mcp "npx @modelcontextprotocol/server-filesystem ."
hawk --mcp "npx @modelcontextprotocol/server-github"

License

MIT — GrayCode AI