honed
Your coding agent's CLAUDE.md, AGENTS.md, and skills, improved from evidence of how it actually worked.
honed reads the sessions your agent ran in a project, has a reviewer agent rate each line of its instructions and skills against what happened, and has a curator rewrite what hurt and keep what helped. Every rating and change lands in a git-tracked journal, so each new version says why it changed, and you review it like a pull request before installing it. It works across Claude Code, Codex, Pi, OpenCode, and Antigravity.
Quickstart
python -m pip install honed
cd your-project
honed setup
honed setup makes the folder a git repository if it is not one, detects the agent (Claude Code, Codex, Pi or
OpenCode; pass --harness claude when it can't tell), installs the /evolve and /reflect skills, and commits only
what it installed. It is safe to run again.
The workspace (.honed/workspace) keeps every version of the configuration and why it changed. Give it a remote:
setup asks, and offers to create a private GitHub repository with gh (--create-remote does it without asking;
--remote URL uses one you have). It is pushed there, the project holds it as a submodule so a clone fetches it, and
honed evolve apply pushes each release. Without a remote (--local) it stays on your machine, out of the project,
until honed evolve remote URL gives it one.
Evolution is per project: each project keeps its own versioned configuration and learns from its own sessions.
/reflect alone can be installed for every project, into the agent's own folder (~/.claude/skills, ...):
honed skills install reflect --global --harness claude.
Work in the project as usual. After three sessions or more, type /evolve in the agent: it reflects on the last
week's sessions, curates, and proposes a new version of the project's instructions and skills. /evolve diff shows
it, the agent amends it when you ask, and /evolve apply installs it. A round is a short Python recipe (evolve.py
in the evolve skill, with its prompts beside it) that you can edit: see the guide.
No project at hand? examples/quickstart/run.sh sets up a toy project whose CLAUDE.md has
a wrong instruction, runs three Claude Code sessions in it, and runs a round that finds and fixes it. The
example evolution report shows four releases, parallel
candidates, merges, and section histories from a Graphify evolution workspace.
Supported agents
| Agent | Read its sessions | Install configurations (project / global) | /evolve in it |
Reflect, curate, merge |
|---|---|---|---|---|
| Claude Code | yes | yes / yes | yes | yes |
| Codex | yes | yes / yes | yes | yes |
| Pi | yes | yes / yes | yes | yes |
| OpenCode | yes | yes / yes | yes | yes |
| Antigravity | yes | yes / no | no | no |
Configurations cover context files (CLAUDE.md, AGENTS.md, …), skills, hooks, and MCP servers, as far as each
agent supports them (Pi has no hooks or MCP servers). Details per harness: runtime support.
The framework
honed is a framework for context engineering: it turns your agents' sessions into evidence, and that evidence into
versioned changes to their context files, skills, hooks, prompts, and MCP servers. It doesn't prescribe an agent
design; it gives you the pieces — a session index and query language, reflectors, curators, mergers, and a
git-tracked journal — to build your own improvement pipelines.
Build agentic context-engineering pipelines on top of honed: inspect sessions, extract reusable lessons and failures, curate versioned updates, evaluate their effect, and install the resulting capabilities into agent environments. The framework is designed to let these pipelines evolve as new artifacts and evaluation methods emerge, drawing direction from work on agentic context engineering, meta-skill evolution, self-evolving agent skills, self-evolving agents, and meta context engineering.
The learning cycle
sessions ─▶ reflection ─▶ ratings in the journal ─▶ curation ─▶ candidate ─▶ merge ─▶ new version
Index sessions from any supported harness:
honed sessions --index sessions.sqlite sync logs/codex-training
honed sessions --index sessions.sqlite query 'select:session'
Reflect, record, and curate:
from typing import Annotated
from pydantic import BaseModel
from honed.curation import Curator
from honed.reflection import Reflector
from honed.resources import CategoricalScale, AgentConfig, Ref
from honed.sessions import Sessions
usefulness = CategoricalScale("usefulness", ["harmful", "neutral", "helpful"], ordered=True)
class Rated(BaseModel):
ref: Ref
usefulness: Annotated[str, usefulness]
class Lesson(BaseModel):
key_insight: str
ratings: list[Rated]
agent = AgentConfig.from_installation("codex", "path/to/project", name="my-agent", version="1.0")
agent = agent.init_workspace("artifacts/my-agent") # git-tracked, with a journal
with Sessions("sessions.sqlite") as sessions:
session = sessions.get() # the most recent session
reflection = Reflector("codex").handoff("Review the configuration against this session.",
session, agent, Lesson)
agent.add_reflection(reflection) # ratings → journal
curation = Curator("codex").curate("Address the reflections.", [reflection], agent, scales=[usefulness])
print(agent.diff(curation.candidate()))
Run pipelines in parallel worktrees (agent.to_worktree(path)) and combine their candidates with
Merger("codex").merge(prompt, [candidate_1, candidate_2]). Install the result into any
harness with agent.install("claude", "path/to/project").
Further reading
- Concepts — every concept, kept in step with the code.
- Documentation — guides and reference; preview it with
python -m pip install -e '.[docs]' && python -m mkdocs serve. - Quickstart example — a toy project and one round, end to end.
- Cookbook —
live_reflect.py,live_ace.py,live_ace_with_merge.py.
Contributing and license
Contributions are welcome: see CONTRIBUTING.md, and report vulnerabilities as SECURITY.md describes. honed is licensed under the Apache License 2.0.
Metadata
Release files for honed 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| honed-0.4.0.tar.gz | 375.8 kB | With provenance | Details for honed-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| honed-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for honed-0.4.0-py3-none-any.whl |
Total release size: 803.8 kB
Release files / honed-0.4.0.tar.gz
| Download URL | honed-0.4.0.tar.gz |
|---|---|
| Size | 375.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
bb22719d6ace406ba3adff15c589cbc2aa76072936a9eaf8bf4f032b401641a1
|
|
BLAKE2b-256 checksum How to use checksums |
c2b626b31063007bd8463ab0531d02a250b4c7ad543a8e151d37b42024a9e77a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logRelease files / honed-0.4.0-py3-none-any.whl
| Download URL | honed-0.4.0-py3-none-any.whl |
|---|---|
| Size | 428.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ecaf24d1e2766905fd5d6627ae82dd477f90fca2b0112eb3f4077e9adb5ef0fb
|
|
BLAKE2b-256 checksum How to use checksums |
de1ea0820420ccaed28885139760fa41e03779a9483039a199c1c6f1b13b3aae
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logSecurity for honed 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for honed-0.4.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.