Manage configuration

An AgentConfig is a named, versioned agent configuration: skills (with their files), context documents such as AGENTS.md, rules, workflows, commands, hooks, MCP servers, and harness-only extensions. It also carries a journal — the history of every section.

Import, edit, install

from honed.resources import Hook, AgentConfig, Skill

agent = AgentConfig.from_installation("claude", "path/to/project", name="graphify", version="1.0")
agent.skills["retry"] = Skill(name="retry", description="Retry failing commands", instructions="# Retry\n…")
agent.install("codex", "path/to/other-project")

Installation writes the configuration in each harness's own layout and records what it owns in a marker file, so reinstalling replaces exactly that. Context documents such as CLAUDE.md are merged by section, keeping the project's own sections.

Hooks per harness. Matchers name a harness's own tools, so hooks often differ per harness: Hook(…, harnesses=["claude"]) installs only into Claude. Owned hooks — agent.owns_hooks = ["graphify *"] — mark hook commands as the agent's wherever they appear: every install replaces them, including ones installed by hand, instead of adding copies.

Revisions and diffs

agent.revision is version@rev_…: the version plus a hash of the configuration files. A journal entry records the revision it applies to. agent.diff(other) is a unified diff of two configurations.

Workspaces

agent = agent.init_workspace("artifacts/graphify")   # git init, initial commit, journal seeded
agent = AgentConfig.from_workspace("artifacts/graphify")
light = AgentConfig.from_workspace("artifacts/graphify", journal=False)   # configuration only

An agent read from or initialized in a workspace remembers it (agent.workspace). add_reflection then also appends to journal.jsonl, and release and to_worktree act on that repository; each first checks that nobody edited the files since the agent was read.

A workspace is the configuration as files plus agent.json (name, version) and journal.jsonl. Files carry markers — each section's lineage ID:

## Limits <!-- res_fd94… -->

Ratings stay in the journal; agent_outline(agent, USEFULNESS, ids=True) shows them per section.

Markers are stripped when a workspace is read, so revisions, installations, and the files reflectors read never contain them. While someone edits, a marker says which section is which: a heading that keeps its marker under a new title is a move, not a removal plus an addition.

The journal

The journal is append-only. It holds ratings (from reflections) and changes (Added, Modified, Moved, Removed — from commits, each with the commit message as its reason).

from honed.resources import record_commits, agent_at

record_commits("artifacts/graphify", agent.journal)        # commits not yet in the journal
agent.journal.changes(target, subsections=True)            # a section's change log, across moves
agent.journal.summaries(USEFULNESS)                        # rating summary per section
before = agent_at("artifacts/graphify", "HEAD~3")          # the configuration at any commit

Rating policies decide which ratings count: count_all, since_last_modification (ratings of a section's current text), and including_subsections(policy) (a parent includes its subsections). agent_outline(agent, USEFULNESS, ids=True) prints every section with its ID and summary.