Skip to main content

honed logo

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)

Source distribution for honed 0.4.0
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)

Table of built distributions (wheels) for honed 0.4.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

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

Select from 2 files

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 log

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

Release history Release notifications | RSS feed

This release

0.4.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page