AI coding agent for your terminal — built for developers, not teams or enterprises (yet).
Quick Start · Features · Usage · Skills · Tools · Architecture · Contributing
hawk is an AI-powered coding agent that lives in your terminal. It reads your codebase, writes and edits files, runs tests, and manages git — all through natural language. Unlike IDE-bound tools, hawk works over SSH, in containers, and on any machine with a shell.
Developer path: one machine, keychain credentials, local memory. Run hawk path to check readiness.
- Model-agnostic — works with Claude, GPT-4, Gemini, DeepSeek, Ollama, and 75+ models through eyrie
- Zero CGO — single static binary, cross-compiled for linux/darwin/windows on amd64/arm64
- Privacy-first — your code never leaves your machine except to the LLM API you choose
- Extensible — 40+ built-in tools, MCP server support, community skill registry
Hawk is in active development. There is no public install script or release channel yet. We are building features, tests, and hardening in the open.
Follow GrayCode for progress. When Hawk is ready to try, we will announce it on graycodeai.gateandtech.in.
git clone https://github.com/GrayCodeAI/hawk && cd hawk
go build -o hawk ./cmd/hawk
./hawk
# First run — paste API key in /config (stored in macOS Keychain / Linux keyring)
# Verify readiness
./hawk pathSee docs/SECURITY-DEVELOPER.md for the credential model. Do not put API keys in shell env or .env for hawk.
Optional for contributors:
go install github.com/GrayCodeAI/hawk@latest # requires a published tagBuilt with Bubble Tea for a smooth, keyboard-driven experience with vim-style keybindings.
| Category | Tools |
|---|---|
| Files | Read, Write, Edit, LS, Glob, Grep |
| Shell | Bash, PowerShell, CronCreate, CronDelete |
| Git | GitCommit, SmartCommit, EnterWorktree, ExitWorktree |
| Web | WebFetch, WebSearch, CodeSearch |
| Tasks | TodoWrite, TaskCreate, TaskList, TaskUpdate |
| Code | LSP diagnostics, CodeSearch, NotebookEdit, SQL (read-only DB exploration) |
| MCP | ListMcpResources, ReadMcpResource |
For larger tasks, decompose work into parallel feature branches (power-user / future team workflows):
hawk mission "Add auth, rate limiting, and logging"Each sub-agent runs in its own git worktree with full autonomy.
Discover and install modular instruction packages for specialized workflows:
hawk skills search api # Search community registry
hawk skills install go-review # Install from GitHub
hawk skills audit # Security scan installed skillshawk now exposes one visible permission command center in chat:
/permissions
/permissions tier <scout|builder|operator|autonomous>
/permissions sandbox <strict|workspace|off>
/permissions mode <default|edits|bypass|dontask|plan>
/permissions allow <rule>
/permissions deny <rule>
/permissions rules
/permissions reset
/permissions save [project|global]
The model is:
Tiercontrols autonomy:ScoutBuilderOperatorAutonomous
Sandboxcontrols the execution boundary:strictworkspaceoff
Rulescontrol explicit allow/deny exceptions.
For normal chat usage, /permissions is the main control surface. Older
permission chat commands have been removed in favor of this single flow.
Connect external tools via Model Context Protocol and get code intelligence through Language Server Protocol. MCP also supports a WebSocket transport (opt-in) in addition to stdio/HTTP.
hawk --watch watches your tree for AI! (do it now) and AI? (answer my question) comments and acts on them automatically — leave a directive in code, save, and hawk responds. Off by default; enabled via the --watch flag.
A bundled GitHub Action (.github/actions/hawk) runs hawk in your pipeline: interactive mode on @hawk mentions in issue/PR comments, automation mode on labeled issues/PRs, and skill dispatch when a prompt begins with / (e.g. /code-review).
The daemon exposes Telegram, Discord, and Slack gateways so you can chat with hawk from your messaging app. Disabled by default; enabled per-channel via daemon config.
An AST-based repository map (internal/context/repomap) gives the model a structural overview of your code. On first run, hawk can auto-analyze the codebase to seed context (default-off, opt-in).
After edits, hawk can run the matching linter and iterate on fixes (bounded retries) before handing back. Opt-in; preserves existing behavior when disabled.
Feed screenshots and images into the conversation for vision-capable models (internal/engine/vision.go).
Read-only sub-agent modes: plan decomposes a task into steps, explore investigates the codebase with a configurable thoroughness budget (quick / medium / very-thorough).
SmartCommit and the diff summarizer generate Conventional Commit messages from your staged changes.
LangGraph-style durable workflows with named, resumable step checkpoints and optional human-in-the-loop approval gates that persist the gate decision.
Request JSON-Schema-constrained responses; results are validated against the schema and retried once on mismatch.
Define personas and eval tasks in YAML (in addition to markdown personas), including per-agent display color and lifecycle hooks.
An optional, non-excludable org-policy rule tier (highest precedence) with HTML-comment stripping of rule files for IT-managed deployments.
hawk # Start REPL
hawk -r abc123 # Resume session
hawk -c # Continue latest session
hawk --provider openai --model gpt-4o # Override provider# Inside the TUI
/permissions
/permissions tier builder
/permissions sandbox workspace
/permissions mode plan
/permissions allow Bash(git:*)
/permissions deny Bash(rm -rf *)
/permissions save projecthawk -p "explain this repo" # Print response, exit
hawk -p "fix tests" --allowed-tools "Bash(go test:*) Edit Read"
hawk -p "review this repo" --permission-mode plan --sandbox workspace
hawk exec "refactor auth module" # Full engine, non-interactive
hawk exec --auto full "add error handling" # Full autonomy
hawk exec --worktree "add rate limiting" # Isolated branch
hawk exec --agent reviewer "review last commit" # Custom personahawk path # Developer path readiness (setup + security + sandbox)
hawk doctor # Full health report (eyrie + yaad + tok panel)
hawk ecosystem # Ecosystem panel only
hawk yaad # Persistent memory graph
hawk yaad search <query> # Search yaad memories
hawk preflight # Quick ready-to-chat check
make path # Developer path verification
make smoke # Build + quick verification scriptSee docs/SECURITY-DEVELOPER.md.
See docs/ecosystem-message-flow.md for how eyrie, yaad, and tok connect during a chat session.
In the TUI: /path, /ecosystem, /yaad, /yaad search <query>, /memory (AGENTS.md).
hawk daemon start # Background HTTP server on port 4590
hawk daemon status # Check if running
hawk daemon stop # Graceful shutdownEndpoints: GET /v1/health, GET /v1/ready (dependency-aware readiness), POST /v1/chat (JSON or SSE streaming)
hawk mission "Add auth, rate limiting, and logging"
hawk mission --workers 6 "Refactor into microservices"
hawk mission --dry-run "What would this decompose into?"hawk works with any LLM provider. Developer path: paste keys in /config (stored in OS keychain) — not shell env or .env. Use hawk credentials status to verify.
| Provider | ID | Key (via /config) |
|---|---|---|
| Anthropic | anthropic |
ANTHROPIC_API_KEY |
| OpenAI | openai |
OPENAI_API_KEY |
| Google Gemini | gemini |
GEMINI_API_KEY |
| OpenRouter | openrouter |
OPENROUTER_API_KEY |
| xAI (Grok) | grok |
XAI_API_KEY |
| Z.AI | z-ai |
ZAI_API_KEY |
| CanopyWave | canopywave |
CANOPYWAVE_API_KEY |
| OpenCode Go | opencodego |
OPENCODEGO_API_KEY |
| Kimi (Moonshot) | kimi |
MOONSHOT_API_KEY |
| Xiaomi (MiMo) Pay-as-you-go | xiaomi_mimo_payg |
XIAOMI_MIMO_PAYG_API_KEY |
| Xiaomi (MiMo) Token Plan | xiaomi_mimo_token_plan |
XIAOMI_MIMO_TOKEN_PLAN_API_KEY (pick region in /config) |
| Ollama (local) | ollama |
OLLAMA_BASE_URL (no API key) |
Provider routing, model resolution, and retries are handled by eyrie.
For deployment-aware routing, set "deployment_routing": true in .hawk/settings.json
or export HAWK_DEPLOYMENT_ROUTING=true. Hawk will route canonical model IDs through
Eyrie's deployment catalog, so new models can be exposed by refreshing the catalog
instead of changing Hawk. In chat, run /refresh-model-catalog to fetch the latest
deployment-aware catalog into ~/.eyrie/model_catalog.json.
hawk is built in Go with a modular, layered architecture:
hawk/
├── cmd/ # CLI entry point (Cobra + Bubble Tea TUI)
├── internal/
│ ├── engine/ # Agent loop, compaction, self-improvement
│ ├── tool/ # 40+ built-in tools with safety layer
│ ├── config/ # Settings, budget tracking, agent personas
│ ├── session/ # Persistence (JSONL, WAL, checkpoints)
│ ├── api/ # HTTP API server
│ ├── daemon/ # Background HTTP/SSE server
│ ├── sandbox/ # Command isolation (landlock, seccomp, docker)
│ ├── permissions/ # User approval system with auto-learning
│ ├── hooks/ # Event-driven plugin system
│ ├── mcp/ # Model Context Protocol client
│ ├── intelligence/ # Code intelligence (repomap, memory, planner)
│ ├── multiagent/ # Mission orchestration, parallel execution
│ ├── observability/ # Analytics, metrics, logging, tracing
│ ├── resilience/ # Circuit breaker, rate limiting, retries
│ ├── feature/ # eval, fingerprint, voice, IDE integration
│ ├── bridge/ # External bridges (sight, inspect, sessioncapture)
│ ├── provider/ # Provider routing
│ └── system/ # Bus, cron, retention, shutdown
├── docs/ # Architecture, security, integration docs
└── testdata/ # Test fixtures
hawk integrates these GrayCodeAI repos in three ways:
go.modmodules: eyrie, sight, inspect, tok, yaad — pinned module requirements.- External checkout +
go.work: eyrie, sight, inspect, tok, yaad, trace — clone ecosystem repos underexternal/<repo>.go.worklists the local external checkouts. CI clones the same layout via.github/actions/checkout-eyrie. - Optional CLI (no Go import): trace — installed separately;
hawkshells intotracefor session capture when present.
Cross-repo types (severity, etc.) are exported from github.com/GrayCodeAI/hawk/shared/types so sight / inspect / tok do not import internal/.
You may keep a personal parent go.work that lists alternate clones on disk for multi-repo development.
| Component | Repository | Purpose |
|---|---|---|
| hawk | This repo | AI coding agent |
| eyrie | GrayCodeAI/eyrie | LLM provider runtime |
| sight | GrayCodeAI/sight | Diff-based code review (hawk sight) |
| inspect | GrayCodeAI/inspect | Site audit library |
| tok | GrayCodeAI/tok | Tokenizer & compression |
| yaad | GrayCodeAI/yaad | Graph-based memory |
| trace | GrayCodeAI/trace | Session capture CLI |
- Go 1.26+
go build ./cmd/hawk # Build binary
go test -race ./... # Run all tests with race detector
make ci # Run full CI suite (lint, test, security)
make cover # Generate coverage reporthawk follows Go conventions: cmd/ for entry points, internal/ for private code, tests alongside source files. See docs/architecture.md for details.
We welcome contributions! Please see CONTRIBUTING.md for development setup, commit conventions, and the PR process.
Quick start:
- Fork and create a branch:
git checkout -b feat/short-description - Make changes in small, focused commits
- Run
make cilocally - Open a pull request
Use Conventional Commits for commit messages — release-please uses them for versioning.
MIT — see LICENSE for details.
© 2026 GrayCode AI