AI Coding Agent for Your Terminal

AI coding agent for your terminal — built for developers, not teams or enterprises (yet).

Quick Start · Features · Usage · Skills · Tools · Architecture · Contributing

Why hawk

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

Status

Hawk is in active development. Contributor source builds are the primary path today while we keep hardening the product in the open. Tagged releases and install assets may exist for validation, but they are not the recommended first path yet.

Follow GrayCode for progress. When Hawk is ready to try, we will announce it on graycodeai.gateandtech.in.

Quick Start (contributors — from source)

git clone https://github.com/GrayCodeAI/hawk && cd hawk
make setup   # clones required support repos into external/ and syncs go.work
go build -o hawk ./cmd/hawk
./hawk

# First run — paste API key in /config (stored in macOS Keychain / Linux keyring)
# Verify readiness
./hawk path

See 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   # only after Hawk and support repo tags are published

Features

Interactive Terminal UI

Built with Bubble Tea for a smooth, keyboard-driven experience with vim-style keybindings.

40+ Built-in Tools

Multi-Agent Mission Mode (optional)

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.

Community Skills

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 skills

Permission Center

hawk 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:

• Tier controls autonomy:
  • Scout
  • Builder
  • Operator
  • Autonomous
• Sandbox controls the execution boundary:
  • strict
  • workspace
  • off
• Rules control 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.

MCP & LSP Support

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.

Watch Mode (AI-comment loop)

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.

CI / GitHub Action

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).

Messaging Gateways (opt-in)

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.

AST Repo-Map & Codebase Analysis

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).

Auto-Lint / Auto-Fix Cycle

After edits, hawk can run the matching linter and iterate on fixes (bounded retries) before handing back. Opt-in; preserves existing behavior when disabled.

Image / Multimodal Context

Feed screenshots and images into the conversation for vision-capable models (internal/engine/vision.go).

Plan & Explore Sub-Agents

Read-only sub-agent modes: plan decomposes a task into steps, explore investigates the codebase with a configurable thoroughness budget (quick / medium / very-thorough).

Conventional-Commit Generation

SmartCommit and the diff summarizer generate Conventional Commit messages from your staged changes.

Durable Workflows & Approval Gates

LangGraph-style durable workflows with named, resumable step checkpoints and optional human-in-the-loop approval gates that persist the gate decision.

Structured Output

Request JSON-Schema-constrained responses; results are validated against the schema and retried once on mismatch.

YAML Agents & Tasks

Define personas and eval tasks in YAML (in addition to markdown personas), including per-agent display color and lifecycle hooks.

IT-Managed Policy Tier

An optional, non-excludable org-policy rule tier (highest precedence) with HTML-comment stripping of rule files for IT-managed deployments.

Usage

Interactive Mode

hawk                              # Start REPL
hawk -r abc123                    # Resume session
hawk -c                           # Continue latest session
hawk --provider openai --model gpt-4o  # Override provider

Permission Examples

# Inside the TUI
/permissions
/permissions tier builder
/permissions sandbox workspace
/permissions mode plan
/permissions allow Bash(git:*)
/permissions deny Bash(rm -rf *)
/permissions save project

Non-Interactive Mode

hawk -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 persona

Diagnostics & ecosystem

hawk 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 script

See 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).

Daemon Mode

hawk daemon start              # Background HTTP server on port 4590
hawk daemon status             # Check if running
hawk daemon stop               # Graceful shutdown

Endpoints: GET /v1/health, GET /v1/ready (dependency-aware readiness), POST /v1/chat (JSON or SSE streaming)

Mission Mode

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

Providers

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

Architecture

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

Ecosystem

hawk integrates these GrayCodeAI repos in three layers:

• Primary product: hawk is the only end-user product surface in this ecosystem.
• Support engines mounted by Hawk: eyrie, yaad, tok, trace, sight, inspect. Hawk imports or shells into these engines behind its own command surface.
• Shared foundation: hawk-core-contracts holds the neutral cross-repo types that keep the engines independent from Hawk internals.

Local development uses:

• go.mod modules: pinned requirements for the support engines and hawk-core-contracts
• External checkout + go.work: clone support repos under external/<repo>; go.work maps the module paths to those local checkouts
• Submodules in this repo: the same external layout is pinned under external/ for reproducible CI and multi-repo work

Cross-repo contracts now live in github.com/GrayCodeAI/hawk-core-contracts so support repos do not depend on Hawk internals. The old hawk/shared/types path has been removed; use hawk-core-contracts/types for shared severity and finding contracts.

Current contract packages:

• hawk-core-contracts/types — severity, findings
• hawk-core-contracts/review — normalized review findings, comments, stats, results
• hawk-core-contracts/verify — normalized verification findings, stats, reports
• hawk-core-contracts/tools — tool call/result contracts
• hawk-core-contracts/events — normalized tool/trace events
• hawk-core-contracts/policy — permission and policy verdict contracts

You may keep a personal parent go.work that lists alternate clones on disk for multi-repo development.

For the consolidated repo map and the current-vs-proposed architecture diagrams, see docs/architecture/hawk-current-vs-proposed.md.

Development

Prerequisites

• Go 1.26+

Build & Test

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 report

Project Structure

hawk follows Go conventions: cmd/ for entry points, internal/ for private code, tests alongside source files. See docs/architecture.md for details.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for development setup, commit conventions, and the PR process.

Quick start:

1. Fork and create a branch: git checkout -b feat/short-description
2. Make changes in small, focused commits
3. Run make ci locally
4. Open a pull request

Use Conventional Commits for commit messages — release-please uses them for versioning.

License

MIT — see LICENSE for details.

© 2026 GrayCode AI