hawk

command module

v0.3.0 Latest Latest Go to latest Published: May 26, 2026 License: MIT Imports: 6 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/GrayCodeAI/hawk

Links

Open Source Insights

README ¶

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. See docs/DEVELOPER-PATH.md.

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

Quick Start

# Install
brew install GrayCodeAI/tap/hawk

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

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

Or install via other methods:

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

# Install 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 build .

Features

Interactive Terminal UI

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

40+ Built-in Tools

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`
MCP	`ListMcpResources`, `ReadMcpResource`

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 System

hawk asks before running dangerous tools. Auto-mode learns from your decisions, with emergency killswitch support.

MCP & LSP Support

Connect external tools via Model Context Protocol and get code intelligence through Language Server Protocol.

Usage

Interactive Mode

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

Non-Interactive Mode

hawk -p "explain this repo"                    # Print response, exit
hawk -p "fix tests" --allowed-tools "Bash(go test:*) Edit Read"
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/DEVELOPER-PATH.md and 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, 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	Key (via `/config`)
Anthropic	`ANTHROPIC_API_KEY`
OpenAI	`OPENAI_API_KEY`
Gemini	`GEMINI_API_KEY`
OpenRouter	`OPENROUTER_API_KEY`
Grok (xAI)	`XAI_API_KEY`
Groq	`GROQ_API_KEY`
DeepSeek	`DEEPSEEK_API_KEY`
Ollama	local — no key (`OLLAMA_BASE_URL` optional)

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, research notes
└── testdata/               # Test fixtures

Ecosystem

hawk integrates these GrayCodeAI repos in three ways:

go.mod modules: eyrie, sight, inspect, tok, yaad — pinned module requirements.
External checkout + go.work: eyrie, sight, inspect, tok, yaad, trace — clone ecosystem repos under external/<repo>. go.work lists the local external checkouts. CI clones the same layout via .github/actions/checkout-eyrie.
Optional CLI (no Go import): trace — installed separately; hawk shells into trace for 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

Development

Prerequisites

Go 1.26+

Build & Test

go build .                    # 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:

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

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

License

MIT — see LICENSE for details.

Documentation ¶

There is no documentation for this package.

Source Files ¶

View all Source files

main.go

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
compat-test command compat-test reads compatibility-matrix.json and runs basic compatibility checks across the listed components.	compat-test reads compatibility-matrix.json and runs basic compatibility checks across the listed components.
internal
api Package api provides an HTTP API server for hawk, consumable by SDKs.	Package api provides an HTTP API server for hawk, consumable by SDKs.
auth
bridge/inspect
bridge/sessioncapture Package sessioncapture provides terminal context capture with delta-based tracking.	Package sessioncapture provides terminal context capture with delta-based tracking.
bridge/sight
catalogtest
cmdhistory Package cmdhistory implements a structured command history store using SQLite.	Package cmdhistory implements a structured command history store using SQLite.
config Package validator provides config validation utilities.	Package validator provides config validation utilities.
container Package container provides Docker container lifecycle management for hawk's sandboxed execution environments.	Package container provides Docker container lifecycle management for hawk's sandboxed execution environments.
daemon Package daemon provides a Telegram gateway for hawk.	Package daemon provides a Telegram gateway for hawk.
diffsandbox
engine This file re-exports symbols from the agent sub-package so that existing callers of engine.SubAgentMode, engine.NewSubAgentBudget, etc.	This file re-exports symbols from the agent sub-package so that existing callers of engine.SubAgentMode, engine.NewSubAgentBudget, etc.
engine/agent Package agent is the namespace for sub-agent orchestration types.	Package agent is the namespace for sub-agent orchestration types.
engine/async
engine/branching
engine/code Package code provides code-aware features: context extraction, lenses, actions, and explainer.	Package code provides code-aware features: context extraction, lenses, actions, and explainer.
engine/compact Package compact provides compaction strategies, types, and helpers for context-window management.	Package compact provides compaction strategies, types, and helpers for context-window management.
engine/control Package control provides engine control-flow safety types — loop detection, stall detection, and backtracking.	Package control provides engine control-flow safety types — loop detection, stall detection, and backtracking.
engine/cost Package cost provides cost tracking, optimisation, and display for the hawk engine.	Package cost provides cost tracking, optimisation, and display for the hawk engine.
engine/ctxmgr Package ctxmgr is the namespace for context budget, decay, packing, providers, visualisation, and read-only context.	Package ctxmgr is the namespace for context budget, decay, packing, providers, visualisation, and read-only context.
engine/diff Package diff is the Stage-1 namespace for diff sandbox, staging, preview, summariser, test selector, and 3-way merge.	Package diff is the Stage-1 namespace for diff sandbox, staging, preview, summariser, test selector, and 3-way merge.
engine/docs Package docs provides documentation generation, external docs fetching, and doc updating types.	Package docs provides documentation generation, external docs fetching, and doc updating types.
engine/errs Package errs provides error context enrichment, grouping, learning, patterns, and recovery for the hawk engine.	Package errs provides error context enrichment, grouping, learning, patterns, and recovery for the hawk engine.
engine/git Package git provides git-context enrichment and remote-forge integration.	Package git provides git-context enrichment and remote-forge integration.
engine/history
engine/intelligence Package intelligence is the Stage-1 namespace for intent classification, capabilities, language support, tool selection.	Package intelligence is the Stage-1 namespace for intent classification, capabilities, language support, tool selection.
engine/io Package io provides clipboard, AI watcher, file watcher, and cron scheduler types.	Package io provides clipboard, AI watcher, file watcher, and cron scheduler types.
engine/lifecycle Package lifecycle is the Stage-1 namespace for session lifecycle, limits, timeouts, and sleep-time operations.	Package lifecycle is the Stage-1 namespace for session lifecycle, limits, timeouts, and sleep-time operations.
engine/memory Package memory provides knowledge, experience, and memory consolidation types.	Package memory provides knowledge, experience, and memory consolidation types.
engine/observability Package observability is the Stage-1 namespace for profiling, debug recording, structured logging, feedback.	Package observability is the Stage-1 namespace for profiling, debug recording, structured logging, feedback.
engine/planning Package planning is the Stage-1 namespace for task planning, decomposition, goals, and suggested tasks.	Package planning is the Stage-1 namespace for task planning, decomposition, goals, and suggested tasks.
engine/project Package project is the Stage-1 namespace for project analysis, snapshots, impact analysis, dep updates, migrations, releases.	Package project is the Stage-1 namespace for project analysis, snapshots, impact analysis, dep updates, migrations, releases.
engine/prompt Package prompt provides prompt-construction and prompt-optimisation types.	Package prompt provides prompt-construction and prompt-optimisation types.
engine/retry Package retry provides retry-queue and smart-retry types for the engine package.	Package retry provides retry-queue and smart-retry types for the engine package.
engine/review Package review is the Stage-1 namespace for self-review / critique / quality scoring types in package engine.	Package review is the Stage-1 namespace for self-review / critique / quality scoring types in package engine.
engine/safety
engine/scaffold Package scaffold is the Stage-1 namespace for scaffolding, recipes, patterns, skills, and few-shot types.	Package scaffold is the Stage-1 namespace for scaffolding, recipes, patterns, skills, and few-shot types.
engine/search Package search provides URL scraping, issue search, and research agent types.	Package search provides URL scraping, issue search, and research agent types.
engine/session Package session is the Stage-1 namespace for session-lifecycle types in package engine.	Package session is the Stage-1 namespace for session-lifecycle types in package engine.
engine/streaming Package streaming is the Stage-1 namespace for response caching, formatting, stream optimisation, thinking protocol, and steering.	Package streaming is the Stage-1 namespace for response caching, formatting, stream optimisation, thinking protocol, and steering.
engine/token Package token is the Stage-1 namespace for token-related types and functions in package engine.	Package token is the Stage-1 namespace for token-related types and functions in package engine.
engine/validation Package validation is the Stage-1 namespace for generated-code validation, schema validation, test loops, and lint loops.	Package validation is the Stage-1 namespace for generated-code validation, schema validation, test loops, and lint loops.
engine/workflow Package workflow is the Stage-1 namespace for workflow + workspace + trajectory types in package engine.	Package workflow is the Stage-1 namespace for workflow + workspace + trajectory types in package engine.
feature/eval
feature/fingerprint
feature/ide Package ide provides IDE integration hints and metadata.	Package ide provides IDE integration hints and metadata.
feature/shellmode Package shellmode implements the ! prefix for direct shell command execution in the REPL input, bypassing the LLM entirely.	Package shellmode implements the ! prefix for direct shell command execution in the REPL input, bypassing the LLM entirely.
feature/taste Package taste implements a learning system that observes user coding preferences and builds a style profile over time to improve agent output alignment.	Package taste implements a learning system that observes user coding preferences and builds a style profile over time to improve agent output alignment.
feature/voice
hawkerr
home
hooks
intelligence/memory
intelligence/planner Package planner implements structured planning that generates artifacts before coding begins.	Package planner implements structured planning that generates artifacts before coding begins.
intelligence/repomap Package repomap generates a lightweight code structure map of a repository by scanning files and extracting top-level symbols using regex-based parsers.	Package repomap generates a lightweight code structure map of a repository by scanning files and extracting top-level symbols using regex-based parsers.
localize Package localize implements hierarchical fault localization inspired by OpenAutoCoder/Agentless.	Package localize implements hierarchical fault localization inspired by OpenAutoCoder/Agentless.
lsp
magicdocs
mcp
mention Package mention implements @-prefixed file mentions in prompt input, enabling users to reference project files that get auto-included as context.	Package mention implements @-prefixed file mentions in prompt input, enabling users to reference project files that get auto-included as context.
multiagent
multiagent/agents
multiagent/parallel
netutil
observability
observability/alerts
observability/logfield
observability/logger Package logger provides structured logging with levels.	Package logger provides structured logging with levels.
observability/metrics Package metrics provides basic metrics collection (counters, timers, gauges).	Package metrics provides basic metrics collection (counters, timers, gauges).
observability/oteltrace Package trace provides Langfuse tracing integration for LLM observability.	Package trace provides Langfuse tracing integration for LLM observability.
onboarding
permissions
plugin
profile Package profile provides runtime profiling helpers.	Package profile provides runtime profiling helpers.
prompt Package prompt provides the system prompt for hawk.	Package prompt provides the system prompt for hawk.
prompts
provider/routing Package routing provides model routing and health checking.	Package routing provides model routing and health checking.
recipe Package recipe also provides declarative provider configuration.	Package recipe also provides declarative provider configuration.
resilience Package circuit provides a circuit breaker pattern for resilience.	Package circuit provides a circuit breaker pattern for resilience.
resilience/health Package health provides health check and readiness probe support.	Package health provides health check and readiness probe support.
resilience/ratelimit Package ratelimit provides token bucket rate limiting.	Package ratelimit provides token bucket rate limiting.
resilience/retry Package retry provides configurable retry logic with exponential backoff.	Package retry provides configurable retry logic with exponential backoff.
rules Package rules provides import/export of AI coding rules between different tool formats (hawk, Cursor, Claude Code, Copilot, Gemini).	Package rules provides import/export of AI coding rules between different tool formats (hawk, Cursor, Claude Code, Copilot, Gemini).
sandbox Package sandbox provides sandbox mode for isolated command execution.	Package sandbox provides sandbox mode for isolated command execution.
scoring
session
snapshot
system
system/bus
system/cron
system/retention
system/shutdown Package shutdown provides graceful shutdown handling for applications.	Package shutdown provides graceful shutdown handling for applications.
system/staleness Package staleness detects rules/skills that are no longer actively used or that contradict observed user behavior.	Package staleness detects rules/skills that are no longer actively used or that contradict observed user behavior.
task
testutil
tool
types Package types provides shared types used across GrayCodeAI hawk-related modules.	Package types provides shared types used across GrayCodeAI hawk-related modules.
update
sarif module
shared
types Package types defines stable shared types for GrayCodeAI libraries (sight, inspect, tok, …).	Package types defines stable shared types for GrayCodeAI libraries (sight, inspect, tok, …).