Fable Harness installs a project-local control layer for AI coding agents. It gives Codex, Claude Code, and compatible agents a repeatable way to remember project decisions, plan work, run decision loops, delegate safely, verify results, and roll back specific changes without turning your repository into hidden chat state.

Install

by prompt

Ask your agent to install it in the current workspace:

Install the Fable-Harness skill (https://github.com/aao-sh/fable-harness) and run it to set up this workspace.

The agent should handle the local project setup, choose the right surface, and run the installer with the workspace context already loaded.

Check Python version:

python --version

  winget install Python.Python.3.12

  brew install [email protected]

  sudo apt update && sudo apt install python3.12

Then use the package-manager entry point:

npx @aao-sh/fable-harness "./path/to/project" --agent auto

Or install into a workspace from this repository:

python "./scripts/install_fable_harness.py" "./path/to/project" --agent auto --with-superpowers

Agent targets:

| Target | Writes instructions to | Installs harness in | |---|---|---| | codex | AGENTS.md | .codex/ | | claude | CLAUDE.md | .claude/ | | any | AGENTS.md | .agents/ | | both | AGENTS.md and CLAUDE.md | all supported surfaces | | auto | detects the workspace | detected surface |

Why Use It

AI agents are strongest when their work is grounded in files, evidence, and repeatable checks. Fable Harness gives them that structure inside your project.

Benefits

• Project-local memory instead of fragile chat-only context.
• Decision traces for audit-sensitive work.
• Semantic notes, RAG, and graph lookup for faster recall.
• A native decision loop: orient, inspect, decide, act, verify, report.
• Safer subagent planning for complex work.
• Protected TDD evidence and closure checks.
• Selective rollback plans instead of broad destructive resets.

Main Workflows

Fable Harness stores durable project knowledge in compact semantic notes, not in raw chat history. Decision traces remain audit evidence, while generated memory shards, retrieval reports, and graph files make recall faster without making every future agent reread everything.

Use it when an agent needs to remember decisions, reload context, search prior work, promote trace evidence, or keep global/model memory from replacing project-local memory.

Planning starts from project evidence: instructions, notes, docs, source files, RAG citations, and graph orientation. If local sources are weak, the harness tells the agent to research before planning; if the task is still underspecified, it interviews the user before inventing requirements.

Use it to keep plans grounded, reviewable, and tied to real files.

The decision loop is the harness core: orient, inspect, decide, act, verify, report. Native loop scripts record events, transitions, checklist evidence, subagent waves, verification, repair attempts, and closure status.

Use it for non-trivial or mutating work where hidden process state would be risky.

Fable Harness separates independent domains from dependent loop steps. Independent domains can become subagent waves; dependent steps stay ordered. This keeps parallel work fast without corrupting generated state, traces, memory, or verification order.

Use it when a task spans separate files, domains, or responsibilities that can progress independently.

Rollback is selective and reviewable. The harness creates rollback plans, checkpoints, backups, and reverse patches before applying changes. It avoids broad destructive commands when the user only wants one file, hunk, or agent change reverted.

Use it when you need to undo specific work without erasing unrelated progress.

✨ Acknowledgements

• Superpowers: Provides the skill framework that enables agents to run complex tasks.

• Special thanks to all community contributors who help maintain and support the project.

📚 References

Frameworks, Playbooks & Workflow Design

• Mark Kashef (@MarkKashef):
  • The Fable Mindset Playbook. Available at Gumroad.
  • 6 Dynamic Workflow Patterns for Claude Code. Available at Gumroad.

Knowledge Graphs & Semantic Memory

• Alexander Shereshevsky (Medium):
  • Your Obsidian Vault Is a Knowledge Graph. Here’s How to Make It Think (quickly). Published in Graph Praxis. Read on Medium.
• Skjæveland, M. G.; Balog, K.; Bernard, N.; Łajewska, W.; & Linjordet, T. (2024):
  • An ecosystem for personal knowledge graphs: A survey and research roadmap. AI Open, Volume 5, Pages 55-69. Available via ScienceDirect.

Graph RAG Implementations

• Oscar Campo (@oscampo):
  • Neural Composer: Local Graph RAG made easy (LightRAG integration). Discussion and implementation framework available on the Obsidian Forum.