agency
An installable Claude Code plugin and a running engine for its model
on the real substrate — graphqlite
(SQLite + Cypher) + fastmcp
(incl. the experimental code-mode transform). One bi-temporal provenance
graph; four concepts (Intent · Capability · Lifecycle · Memory);
code-mode IS the contract, exposed isomorphically over MCP · Skills ·
a bash CLI.
v0.1. Capabilities self-register by reflection, and the engine authors
and validates its own plugin install.
Read first
docs/vision/GOALS.md — the why (8 goals
- 5 non-goals + a goal-to-code map). One page.
docs/vision/CORE.md — the canon (how the
four concepts compose).AGENTS.md — the operational guide for any agent
working in this repo (verify via git ls-remote, never local HEAD).AGENCY_PROTOCOL.md — the remote-async-agent
doctrine (COMPLETED ≠ done; the four-case routing; recovery flow).CLAUDE.md — three rules for any Claude Code session
working here.
Install (Claude Code)
This repository is an installable Claude Code plugin and its own
single-plugin marketplace. The plugin ships:
.claude-plugin/plugin.json # install descriptor (+ userConfig.jules_api_key, sensitive)
.claude-plugin/marketplace.json # single-plugin marketplace catalogue
.mcp.json # declares the Agency MCP server (bare `agency-mcp` on PATH)
hooks/hooks.json # SessionStart hook (auto pipx-install on first session)
hooks/session-start # the install script (pipx-only, Spec 065)
hooks/run-hook.cmd # cross-platform CMD+bash polyglot wrapper (Spec 064)
skills/using-agency/SKILL.md # the broad-trigger entry meta-skill
skills/help/SKILL.md # the /agency:help macroskill (live capability map)
commands/help.md # the /agency:help slash command
One canonical install path: pipx (Spec 055/065 doctrine).
The legacy .venv bootstrap (bin/agency-install) AND the
bin/agency / bin/agency-mcp shims have ALL been removed (Spec
065 — PR #19 review surfaced fragility in the multi-step fallback
chain). The pipx-installed agency / agency-mcp / agency-doctor
console-scripts ARE the install. .mcp.json references bare
agency-mcp (PATH resolution) like episodic-memory does.
Pipx install (canonical)
pipx install git+https://github.com/netzkontrast/agency@main
# …or for a local checkout:
pipx install --editable /path/to/agency
# Verify:
agency-doctor # JSON health report; exit 0 if ok, 1 if degraded
agency-mcp # MCP server on stdio (bind via .mcp.json)
agency search "any-keyword" # bash CLI
The plugin ships three console-scripts (agency-mcp, agency,
agency-doctor) registered in pyproject.toml. After pipx install,
all three land on PATH. .mcp.json references bare agency-mcp
(resolved from PATH — episodic-memory pattern; no bin/ shim).
If agency-mcp isn't on PATH the MCP server simply fails to start.
The SessionStart hook (below) prevents this on first session.
From the GitHub marketplace
In Claude Code:
/plugin marketplace add netzkontrast/agency
/plugin install agency@agency
This sets up the plugin tree under ${CLAUDE_PLUGIN_ROOT}. A
SessionStart hook (Spec 062, hooks/session-start) auto-runs
pipx install --editable ${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}} on the
first session so agency-mcp lands on PATH without a manual step.
The hook is idempotent — every subsequent session early-exits when
the binary is already installed. Editable mode means future
marketplace plugin updates flow through automatically.
Claude Code Web environments: the hook removes the need to
manually pipx install after a marketplace install. The first
session shows a one-time agency: installing via pipx (one-time) — this may take ~5s line; thereafter the plugin just works.
Pipx-direct doctrine (Spec 065): the SessionStart hook is a
single-path install — pipx only. Spec 063's multi-step fallback
(pip --user → per-project .agency/.venv) was removed after PR #19
review surfaced 4 P2 correctness issues in the chain. If pipx
isn't on PATH the hook prints a clear install hint
(https://pipx.pypa.io/stable/installation/) and exits 0. Users
install pipx once; the plugin just works thereafter.
