agentd

README

---

agentd

A local daemon that proxies, guards, and observes coding-agent hooks — once, for every agent.

---

agentd sits between your AI coding agents (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, Kimi Code) and your hook logic. Agents invoke a thin CLI entrypoint; a user-level daemon applies policies, dispatches sync and async pipelines, and returns provider-correct responses. Built on agenthooks for wire compatibility.

Status: v0.0.5 (trajectory stats, session stats). Roadmap history: PROGRESS.md.

Documentation

• User guide (English) — default (why agentd)
• Руководство (русский) (зачем нужен)
• Keeping docs current: docs/en/maintaining.md

Contributor design and conventions: DESIGN.md, AGENTS.md, CONVENTIONS.md. How to contribute: CONTRIBUTING.md.

Research

Structured verbatim excerpts from primary sources — used when designing provider support, hooks, and conventions. Each tree has its own index and SOURCES.md.

Tree	Focus
research/best-practice	Go best practices (Go ≥ 1.26.7)
research/claude-code	Claude Code docs — agent loop, hooks, MCP, settings, skills, plugins, cloud, enterprise
research/codex	Codex / ChatGPT Learn docs — sandbox, hooks, MCP, cloud, enterprise
research/cursor	Cursor docs — agent loop, hooks, MCP, settings, enterprise
research/gemini	Gemini CLI docs (snapshot 2026-08-29) — agent loop, hooks, MCP, settings, skills, extensions, Managed Agents API, Antigravity migration delta

Stub dirs for other agents (opencode, kimi-code) live under research/ and will fill in the same shape.

Why agentd?

Coding-agent hooks are powerful but painful to operationalize:

• Duplicated glue — each provider speaks a slightly different JSON dialect, timeout unit, and failure mode.
• Heavy cold starts — spawning full hook logic on every tool call adds latency.
• Mixed concerns — blocking guards, audit webhooks, and metrics want different lifecycles but share one process.

agentd centralizes hook logic in a long-lived daemon while keeping the agent-facing contract compatible with agenthooks. You configure declarative guards and dispatch routes; the daemon hot-reloads config without re-reading disk on every event.

Features

• Universal hook proxy — one CLI surface (agentd hook run) for all supported agents
• Sync + async + hybrid dispatch — blocking decisions for the agent, fire-and-forget observability in parallel or after sync
• Declarative guards — secrets, shell, MCP, path policies via YAML
• Approvals & temporary blocks — Ask once / approve with TTL; runtime overlay persisted across restarts
• Efficient config reload — in-memory snapshots, fsnotify with debounce; zero config I/O on the hot path
• Cross-platform IPC — gRPC over Unix domain sockets (Linux/macOS) or named pipes (Windows)
• Provider-faithful I/O — stdout/stderr discipline and exit codes handled per agenthooks codecs
• Ops Status — queue depth and async overflow drop counter on daemon status

Supported agents

Agent	Hook install target	Entry command	Guide
Claude Code	.claude/settings.json, plugins	agentd hook run --provider=claude-code	docs
Cursor	.cursor/hooks.json	agentd hook run --provider=cursor	docs
OpenAI Codex	hooks.json / config.toml	agentd hook run --provider=codex	docs
Gemini CLI	.gemini/settings.json	agentd hook run --provider=gemini	docs
OpenCode	.opencode/plugin shim	agentd hook serve --provider=opencode	docs
Kimi Code	user ~/.kimi-code/config.toml only	agentd hook run --provider=kimi-code	docs

Provider quirks (Ask support, empty stdout, timeouts, install scope): docs/en/providers.md.

Architecture

 Agent (Claude/Cursor/…)          agentd CLI              agentd daemon
        │                    (hook edge)              (gRPC + dispatch)
        │  spawn per event          │                         │
        └──── hook run ──────────►│ decode ── Invoke ──────►│ sync pipeline  ──► decision
                                  │                         │ async pipeline ──► queue → sinks
                                  │◄── encode stdout ───────┘
        ◄── JSON + exit code ─────┘

• Hook CLI — decode/encode only; no business logic
• Daemon — routing, guards, forward targets (HTTP, exec, gRPC, logs)
• Config — layered YAML with atomic in-memory snapshots

Details: DESIGN.md

Requirements

• Go 1.26+ (to build from source)
• A supported coding agent (see table above)
• Linux, macOS, or Windows

Installation

go install github.com/macrox-pro/agentd@latest

Pre-built binaries for linux/darwin/windows are published on GitHub Releases (goreleaser).

Details: docs/en/installation.md.

Quick start

1. Start the daemon (one instance per user). If ~/.agentd.yaml is missing, start creates a minimal bootstrap automatically:

agentd daemon start
agentd daemon status

2. Customize user config (optional — edit ~/.agentd.yaml after start, or create it yourself first):

version: 1
policy:
  fail: fail_closed
  # offline defaults to fail_open — agents keep working if the daemon is down
guards:
  secrets:
    enabled: true
    action: ask

3. Install hooks for your agent (example: Claude Code, project scope):

cd your-repo
agentd install --provider=claude-code --scope=project

4. Verify — trigger a tool call in your agent; check daemon status:

agentd daemon status --json

For OpenCode, use agentd hook serve --provider=opencode in generated plugin config (see DESIGN.md §1).

Full walkthrough: docs/en/getting-started.md.

Configuration

Configuration merges four layers: defaults → ~/.agentd.yaml → .agentd.yaml (project) → runtime overlay (daemon-written). State (log, runtime overlay, sessions) lives under the state directory, not ~/.agentd/.

Minimal dispatch example (sync guard + async audit):

dispatch:
  - name: gate-and-audit
    match: { kind: [tool.pre] }
    mode: parallel
    sync:
      - target: builtin
        guards: [secrets]
    async:
      - target: log
        level: info

Full schema: docs/en/configuration.md · layer/runtime overlay: DESIGN.md §7

CLI overview

Command	Purpose
agentd daemon start	Start the user-level daemon
agentd daemon enable	Register login autostart (see Operations)
agentd daemon disable	Remove login autostart
agentd daemon stop	Graceful shutdown
agentd daemon status	Health, config generation, queue depth, async drops
agentd hook run	Agent entrypoint — blocking hooks
agentd hook notify	Codex notify path (async)
agentd hook serve	OpenCode NDJSON bridge
agentd install	Write agent hook configs (via agenthooks)
agentd config validate	Validate YAML offline (CI-friendly)
agentd config enable FEATURE	Curated toggles (trajectory, guards) — user/project YAML
agentd config disable FEATURE	Turn off a curated toggle
agentd config get FEATURE	Effective on/off + winning layer (no runtime)
agentd config show	Inspect merged config
agentd config patch	Patch runtime overlay (persisted)
agentd config record-decision	Record approval after Ask
agentd dispatch routes	Show compiled dispatch routes
agentd session subscribe	Live trajectory stream (daemon required)

Trajectory (opt-in): every supported agent’s hooks are traceable on one stream; transcript/thinking depth varies by provider — not “everything the model sees everywhere.”

Provider	L2 import
claude-code, codex	supported
cursor	partial (--path)
gemini, opencode, kimi-code	none

Details: docs/en/trajectory.md · DESIGN §14.3

Rationale for each command: docs/en/cli.md · DESIGN §6 (architecture notes)

Development

git clone https://github.com/macrox-pro/agentd.git
cd agentd
make generate   # protobuf (requires buf)
make test       # go test -race
make lint       # golangci-lint + buf lint
go test -tags=integration ./...   # optional daemon↔hook integration

See CONTRIBUTING.md and AGENTS.md.

Contributing

Issues and pull requests are welcome. Please read CONTRIBUTING.md (and AGENTS.md before submitting code).

License

MIT — see LICENSE.

Acknowledgements

Hook wire formats and provider compatibility powered by speakeasy-api/agenthooks.

Documentation

Overview

Copyright © 2026 Aleksandr Garin <garin1221@yandex.ru>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.