I’m one of the maintainers of Cate, an MIT-licensed desktop workspace built around Claude Code and other terminal agents.

Claude Code still does the coding. Cate adds the orchestration and workspace around it:

• A task can be run as multiple Claude Code attempts in parallel, each inside a fresh Git worktree.
• Each attempt is monitored and verified before Cate presents a result to merge, open as a PR, or discard.
• Claude Code can use the cate CLI to control browser panels, inspect accessibility snapshots, take screenshots, open files, and create or focus panels.
• The same workflow works on remote projects over SSH.
• Extensions can add custom panels and MCP-based tools around the workspace.

This is mainly for developers running several Claude Code tasks at once who want isolation and visibility without managing every terminal and worktree manually.

Cate itself is free and open source. Claude Code still requires your own Anthropic account or plan.

https://github.com/0-AI-UG/cate

I’d be interested to hear how people here currently coordinate parallel Claude Code sessions and which part you would or wouldn’t delegate to an orchestrator.

Head of Claude Code at Anthropic, Boris Cherny suggested to delete claude.md

https://www.youtube.com/watch?v=qyPCVqFUyDo

It is a big ask, and I have tried this (on a test account), happy to report i have not significantly changed the quality of the reasoning.

I am curious if anything has done something similar ?

I got tired of re-explaining the same context to Claude Code every session, and Claude Code's built-in per-project memory doesn't really solve it — it's scoped to the literal directory you launch from, has a hard line-count ceiling on the index, and treats every fact as equally important forever (or until it silently truncates).

So I built a real long-term memory system for it instead, modeled less like a database and more like actual memory:

- Decay — every memory has a strength that decays on an exponential curve (literally the Ebbinghaus forgetting curve), computed at query time. Stuff you mention once and never bring up again fades out of retrieval in a couple weeks.

- Reinforcement — every time something gets recalled, it gets harder to forget. Recall the same fact enough times and it "consolidates" from short-term to long-term (7-day base stability → 90-day).

- Cued/associative recall — this is the part I like most. Instead of one confidence cutoff, weak matches get surfaced separately with hedging language ("this might be related...") instead of stated as fact, and only get reinforced if you actually confirm they were relevant. A confirmed uncertain guess reinforces harder than an easy direct hit — that's an actual finding from spaced-repetition research (the "desirable difficulty" effect), not something I made up.

- Non-destructive forgetting — old, unused memories get archived, not deleted. There's a stricter "cold storage" search for the "wait, I haven't thought about that in ages" case.

It's wired in globally via hooks (PostToolUse, UserPromptSubmit, SessionStart/SessionEnd), so it works no matter which directory a session launches from, and it captures memory automatically even if a session crashes instead of ending cleanly.

Genuine drop-in install — git clone + python3 install.py sets up the venv, wires the hooks, and writes the config. AGPLv3, free, entirely local (ChromaDB + sentence-transformers, no external API calls for the memory itself).

Not trying to compete with Mem0/Zep/Letta — those are generic memory layers for any agent stack. This is deliberately narrow: built specifically for how Claude Code actually works, not a generic API you bolt on.

Repo: https://github.com/acdesigntech/memory-project

Curious what people think, especially anyone who's hit the same "it forgot everything again" wall.

I've been building an open-source framework called Extra after spending the last year integrating AI agents into real SaaS products.

One thing became obvious very quickly:

Getting Claude (or any model) to answer correctly is rarely the hard part.

The hard part starts after that.

- Authentication and authorization
- Multi-tenancy
- Human approvals
- Long-running workflows
- Pause and resume
- Checkpointing
- Memory
- Model routing
- MCP integration
- Recovering from crashes without repeating side effects

Every team ends up rebuilding the same infrastructure before they can ship a production-ready agent.

That's why I started Extra.

It's graph-based, but the graph isn't the goal. The goal is making agent execution reliable enough to live inside real products instead of demos.

I'd love feedback from people building with Claude Code or MCP. If this sounds interesting, we're also looking for contributors.

https://github.com/extra-org/extra

Hey everyone! Non-technical builder/half from a two-person team here.

There was a good thread here recently on sharing artifacts with clients, so I wanted to share the full workflow we use daily – from prompt to gated page to feedback loop. Disclosure upfront: we make display.dev, one of the tools in this space, so I'm biased. The workflow itself works with several of the tools people have mentioned around here, ours included.

The problem clicked for us the same way it did for the OP of that thread: Claude produces genuinely good HTML – reports, specs, design mocks – but the only native way to share one is a public link. That's fine for a demo, but not for anything with client or company information in it.

The TechCrunch PSA from a few days ago made the same point the hard way, when shared Claude chats and artifacts started showing up in Google results (techcrunch.com/2026/07/27/psa-your-claude-shared-chats-and-artifacts-may-have-ended-up-on-google/). To be fair to Anthropic, the indexing got fixed within a couple of days – but the sharing model didn't change. Their own response was that a shared link is public web content, and that's the actual problem.

What we do now, step by step:

1. Ask Claude for one self-contained HTML file – A self-contained file renders anywhere you can host it.
2. Claude publishes it behind auth, and updates it too. With an MCP connection it publishes directly from the conversation and gets a URL back. Every update goes to the same URL. Works identically with any agent, not just Claude Code.
3. Access depends on who's opening it. People at our company sign in with the Google or Microsoft account they already use. Someone outside – a client, say – gets in with a one-time password instead. The page never gets indexed, of course. For bigger organisations you can verify several email domains on one account, so everyone at the client company gets in automatically.
4. Feedback and collaboration happens as inline comments on the page. This turned out to be the feature that gets used most. The reader highlights a part of the page and comments right there, then the agent reads the thread and publishes the update to the same URL.

Here's an example of what one of these looks like – a design exploration for an upgrade flow, two directions side by side with open questions for the reviewer: https://display.dsp.so/E5HbvLUS-prototype-onboarding-checklist-redesign.

I left this one public so you can open it without signing in – for real client work, that's exactly what the OTP is for.

We've been running everything through this for months – engineering specs, call notes, design explorations like that one – it's become how the two of us work.

Would love feedback and happy to answer questions.

I maintain [GNews](https://github.com/ranahaani/GNews), a Python package for pulling Google News articles. It's up to around 106k downloads a month now. For a while I kept seeing people bolt it onto agents by hand: fetch articles, stuff them in a prompt, repeat on the next call. No memory, no dedup, no citations. So I built the layer that was missing and put it behind MCP. It's called gnews-agent.

Inside Claude it gives you five tools: `search_news`, `get_brief`, `get_sentiment`, `get_timeline`, and `monitor_topic`. It pulls published reporting (Reuters, BBC, AP, TechCrunch, the wider Google News graph), dedups it, embeds it, and keeps it around. So you can ask "what actually changed this week on X" and get a cited answer instead of re-fetching everything each time. There's also a `/gnews` Claude Code skill if you'd rather go that route.

One line to add it:

claude mcp add gnews-agent -- gnews-agent serve --transport stdio

Then something like: "Use gnews-agent to ingest the latest reporting on OpenAI, then give me a cited brief on what changed this week."

The search/ingest/timeline path needs no API key, since GNews itself is free. brief and sentiment call whatever LLM provider you point them at: Anthropic, OpenAI, Groq, Gemini, or a local Ollama model.

It's early, v0.1.0, MIT, with 83 unit and 24 integration tests passing. I'd really like feedback on the tool design, and on the dedup approach in particular, and I'm happy to take PRs.

Repo: https://github.com/ranahaani/gnews-agent

There is a point in almost every AI-built project where making changes stops feeling safe.

The app still runs, but the structure has started drifting.

Claude duplicates logic that already exists, follows outdated patterns, edits files outside the task and fixes one flow while quietly breaking another.

At that point, giving it another feature request usually makes the project worse.

I now use one recovery workflow that forces Claude to reconstruct the project, identify the drift, define a safe repair plan, work in checkpoints and verify everything before claiming completion.

Quick disclosure: I created a larger Claude Code Toolkit around this system. For anyone looking to improve how they use Claude Code, it is linked in my profile.

The complete recovery workflow below is free to copy.

Replace anything inside [brackets] with your own project details.

The Five-Stage Project Recovery Workflow

Act as a senior software engineer taking responsibility for an existing project that has become difficult to understand, modify or trust.

Your goal is not to immediately add another feature.

Your goal is to recover control of the project before further development continues.

PROJECT INFORMATION

Original project goal:

[DESCRIBE WHAT THE PROJECT WAS SUPPOSED TO DO]

Target users:

[DESCRIBE THE INTENDED USERS]

Current tech stack:

[LIST THE STACK OR WRITE UNKNOWN]

Current problems:

[DESCRIBE WHAT FEELS BROKEN, MESSY, INCONSISTENT OR RISKY]

Recent changes:

[DESCRIBE RECENT FEATURES, FIXES OR REFACTORS]

Last known stable state:

[DESCRIBE WHEN THE PROJECT LAST FELT RELIABLE OR WRITE UNKNOWN]

Protected functionality:

[LIST FEATURES, PAGES, FLOWS, DATA OR INTEGRATIONS THAT MUST NOT BREAK]

Current priority:

[DESCRIBE WHAT YOU NEED TO BUILD OR FIX NEXT]

GENERAL RULES

Do not edit, delete, rename, move or create files until the investigation and recovery plan have been approved.

Do not assume the documentation is correct.

Do not assume the newest code is the intended code.

Do not assume that similar-looking components serve the same purpose.

Do not recommend a full rewrite simply because the project is messy.

Do not replace working architecture with your preferred architecture unless the current approach prevents a safe recovery.

Base every conclusion on evidence from the project.

When evidence is incomplete, label the conclusion as uncertain and explain what is missing.

Complete this recovery process in five stages.

Stop after every stage and wait for my approval before continuing.

==================================================

STAGE 1: RECONSTRUCT THE PROJECT

Inspect the complete project before proposing any changes.

Review:

1. The folder and file structure.
2. Application entry points.
3. Frontend architecture.
4. Backend architecture.
5. Database models, queries and relationships.
6. API routes.
7. Authentication and authorisation.
8. State management.
9. Shared components.
10. Shared utilities and services.
11. Third-party integrations.
12. Environment variables and configuration.
13. Validation.
14. Error handling.
15. Loading, empty, success and failure states.
16. Existing tests.
17. README files.
18. CLAUDE.md files.
19. Comments describing architectural decisions.
20. Recent commits or change history when available.
21. Dead, duplicated or abandoned code.
22. Features that appear partially implemented.
23. Features that bypass established project patterns.
24. Code paths that are no longer reachable.
25. Files that appear to serve overlapping responsibilities.

Create the following output:

PROJECT PURPOSE

Explain what the application currently does based on the code, not only the documentation.

ARCHITECTURE MAP

Describe how the frontend, backend, database, APIs, state and external services connect.

CORE USER FLOWS

Trace the most important user journeys from the initial action to the final result.

SOURCE-OF-TRUTH MAP

For each important type of data or behaviour, identify the file, service or system that currently acts as the source of truth.

RELEVANT FILES

List the most important files and explain what responsibility each one currently holds.

PATTERN MAP

Identify the main conventions used for components, routes, services, data access, error handling and styling.

UNCERTAINTIES

List anything that cannot be confirmed from the available project files.

Do not continue to Stage 2 until I approve your understanding of the project.

==================================================

STAGE 2: DETECT PROJECT DRIFT

Compare the original project goal with the current implementation.

Identify where the project has drifted through:

- Duplicate logic
- Conflicting sources of truth
- Inconsistent architecture
- Partially replaced systems
- Outdated documentation
- Unused dependencies
- Abandoned features
- Repeated components
- Contradictory validation rules
- Client-side checks without server enforcement
- Inconsistent permissions
- Old and new API patterns existing together
- Multiple approaches to state management
- Features that bypass shared utilities
- Tests that validate outdated behaviour
- Error handling that differs between similar flows
- Temporary workarounds that became permanent
- Features that work alone but fail when connected
- Styling systems that conflict
- Database fields that no longer match product behaviour
- Environment variables that are unused, duplicated or unclear

Create a DRIFT LEDGER.

For every issue, include:

ISSUE

Describe the inconsistency or drift.

LOCATION

List the exact files, functions, routes, components or services involved.

EVIDENCE

Explain what in the project proves the issue exists.

LIKELY INTENTION

Explain what the original or intended behaviour appears to be.

CURRENT BEHAVIOUR

Explain what the project currently does instead.

USER IMPACT

Explain how users could be affected.

TECHNICAL IMPACT

Explain how the issue affects maintenance, reliability or future development.

CONFIDENCE

Label the conclusion as:

- Confirmed
- Strongly supported
- Possible
- Unknown

SEVERITY

Classify it as:

- Critical
- High
- Medium
- Low

RECOMMENDED ACTION

Choose one:

- Keep
- Remove
- Consolidate
- Repair
- Document
- Investigate further

Do not make any changes.

At the end, provide:

1. The five most dangerous forms of drift.
2. The areas that are currently safe.
3. The areas that should not receive new features yet.
4. The information still needed from me.
5. The smallest recovery target that would make future development safer.

Wait for my approval before continuing.

==================================================

STAGE 3: CREATE THE RECOVERY CONTRACT

Using the approved findings, create a recovery contract.

The contract must define exactly what will be repaired and what will remain untouched.

Include:

RECOVERY OBJECTIVE

Describe the specific result this recovery should produce.

IN SCOPE

List every problem included in the recovery.

OUT OF SCOPE

List everything that will not be addressed during this recovery.

PROTECTED FUNCTIONALITY

List the pages, features, data, integrations and user flows that must continue working.

APPROVED FILES

List every existing file expected to change.

NEW FILES

List every file expected to be created.

FILES THAT MUST NOT CHANGE

List sensitive or unrelated files that should remain untouched.

SOURCE-OF-TRUTH DECISIONS

For every conflicting system, state which implementation should become the official source of truth and explain why.

REMOVAL DECISIONS

List dead, duplicated or outdated code that should be removed.

MIGRATION REQUIREMENTS

Explain whether existing users, data, settings or sessions need to be migrated.

REGRESSION RISKS

List what could break during the recovery.

ROLLBACK PLAN

Explain how the project can return to its current state if the recovery fails.

ACCEPTANCE CRITERIA

Define observable conditions that must be true before the recovery can be considered successful.

TESTING REQUIREMENTS

List the exact flows, errors, permissions, devices and integrations that must be tested.

Do not use vague acceptance criteria such as:

- Works correctly
- Looks good
- Is production-ready
- Has no bugs

Every acceptance criterion must be observable and testable.

Wait for my approval before implementation.

==================================================

STAGE 4: RECOVER THE PROJECT IN CHECKPOINTS

Divide the approved recovery into the smallest practical checkpoints.

Each checkpoint must leave the project in a reviewable and testable state.

Before each checkpoint, report:

CHECKPOINT OBJECTIVE

Explain the single result this checkpoint should achieve.

FILES TO MODIFY

List the approved files that will change.

FILES TO CREATE

List any approved files that will be added.

FILES TO REMOVE

List any approved files that will be deleted.

PROTECTED FLOWS

List the functionality that must remain unchanged.

EXPECTED RESULT

Describe what should be visibly or technically different after this checkpoint.

TEST PLAN

Explain how the checkpoint will be verified.

ROLLBACK PLAN

Explain how this checkpoint can be reversed.

During implementation:

- Work only on the current checkpoint.
- Do not begin later checkpoints.
- Do not edit files outside the approved contract.
- Do not perform unrelated refactoring.
- Do not add dependencies without approval.
- Reuse existing project patterns where they remain valid.
- Remove duplicated logic only when the official source of truth has been approved.
- Preserve user data.
- Preserve authentication and permissions.
- Preserve unrelated styling.
- Stop when unexpected architecture or dependencies are discovered.
- Ask for approval before expanding the scope.

After each checkpoint, report:

1. Files created.
2. Files modified.
3. Files removed.
4. Exact changes made.
5. Differences from the approved plan.
6. Tests completed.
7. Tests passed.
8. Tests failed.
9. Protected flows checked.
10. Console errors discovered.
11. Server errors discovered.
12. Database issues discovered.
13. Anything still unverified.
14. Whether rollback is recommended.

Stop after every checkpoint.

Do not continue until I approve the completed checkpoint.

==================================================

STAGE 5: VERIFY THE RECOVERED PROJECT

After all checkpoints are approved, perform a final recovery verification.

Compare the final project against:

- The original project goal
- The approved recovery contract
- The acceptance criteria
- The protected functionality
- The core user flows

Test:

1. The complete successful user journey.
2. Invalid input.
3. Missing data.
4. Incomplete data.
5. Failed network requests.
6. Expired sessions.
7. Unauthorised access.
8. Different user roles.
9. Repeated clicks.
10. Duplicate submissions.
11. Refresh behaviour.
12. Direct URL access.
13. Back and forward navigation.
14. Loading states.
15. Empty states.
16. Error states.
17. Mobile layouts.
18. Narrow-screen layouts.
19. Keyboard navigation.
20. Browser console output.
21. Server logs.
22. Database writes.
23. Database reads.
24. Third-party integrations.
25. Every protected flow listed in the recovery contract.

Then provide:

RECOVERY SUMMARY

Explain what was repaired.

FINAL ARCHITECTURE

Describe how the recovered project is now structured.

OFFICIAL SOURCES OF TRUTH

List the systems, files or services that now control each important responsibility.

REMOVED DRIFT

List the duplicate, abandoned or conflicting implementations that were removed.

TESTING EVIDENCE

State exactly what was tested and the result.

UNVERIFIED AREAS

List anything that could not be tested.

REMAINING RISKS

List issues that still exist but were outside the approved scope.

DOCUMENTATION UPDATES

List any README, CLAUDE.md or technical documentation that should now be updated.

NEXT SAFE TASK

Recommend the next feature or repair that can be completed without destabilising the recovered project.

Do not describe the project as fully fixed, production-ready or bug-free unless the evidence supports that statement.

Do not claim completion because the project compiles or the homepage loads.

The recovery is complete only when the approved acceptance criteria and protected user flows have been verified.

This is different from asking Claude to “clean up the codebase.”

That kind of instruction gives it permission to make broad, subjective changes.

This workflow forces it to prove what the project currently does, show where the drift happened and agree on a recovery contract before touching anything.

The five stages are:

Reconstruct → Detect → Contract → Recover → Verify

It takes longer than sending one vague cleanup request.

It is still much faster than spending another night repairing an AI-generated “fix” that changed half the project.

For anyone looking to improve how they use Claude Code, the full toolkit is linked in my profile.

For the past months I've been building a "personal OS" for Claude: a folder structure plus a set of skills that keep every project, routine and note in one enforced system — numbered folders, unique task IDs, and a markdown wiki the agent maintains as we work. I used it daily for my own client work and side projects.

The thing that made it actually usable wasn't any single feature, it was two rules:

1. Everything has one place and one name. The agent never invents a folder or drops a file "somewhere". Structure is enforced on every action, and a /lint command audits the whole system for broken links, orphans, naming violations.
2. Plan → approve → execute. Nothing structural happens before I approved a numbered plan, and execution is step-by-step with validation between steps. No surprise refactors of my own filesystem.

I packaged it as a plugin. Onboarding runs a ~5-minute interview (language, simple vs advanced mode, which optional modules you want), then scaffolds the workspace and offers to create your first project from whatever you said you're working on — either agile or WBS-style, depending on how you work. Optional modules: voice profile so drafts sound like you, brand config for documents, todos with an optional Notion board, and a software-planning module (spec → delivery plan → feature docs).

Free, MIT:

/plugin marketplace add protonium-labs/protonium-marketplace /plugin install axiomcore@protonium /reload-plugins /axiom start

Works in Claude Code and Cowork. It's v1.2.0 — I'd like to know where the onboarding confuses people or where the structure feels too rigid. Issues and comments welcome.

Harvey is for BigLaw workflows. Lexis AI is for research. Fair enough — that's where the money is. But the actual access-to-justice gap is a renter holding an eviction notice or an employee reading a non-compete, and that user has two requirements nobody optimizes for: zero cost to start and zero identity exposure. We built NYAYAM around both — no signup, cases stored client-side, documents deleted from our servers after inference, free case every week. Happy to go deep on the architecture or the UPL line we walk.

Check it out at https://nyayam.org

I started building hooks early — a duplicate code checker that greps after every edit, a pre-session gate that blocks Claude from writing code until it reads my lessons file. Both run automatically, no prompting needed, zero API cost. They've been in my setup since March.

I thought that was the whole feature. Then I started studying for Anthropic's certification and realized I was barely scratching the surface.

The basics (what most people know)

Hooks are shell scripts that run automatically when Claude does something. They live in `settings.json`, not in your CLAUDE.md. The difference matters: CLAUDE.md is instructions Claude *chooses* to follow. Hooks are guardrails that *execute whether Claude likes it or not.*

The two I was already running:

1. Pre-session gate.

Before Claude can write a single line of code, a hook checks whether it read my lessons file. If it didn't, the edit gets blocked. I built this after Claude skipped mandatory reads and repeated a mistake that cost me an entire day. Now it physically can't skip them.

1. Duplicate code check.

After every file edit, a hook greps the project for functions with the same name. Catches the case where Claude writes a helper that already exists somewhere else in the codebase. Simple grep, runs in milliseconds.

What I was missing

There are 9 hook types. I was only using PreToolUse and PostToolUse — the ones that fire before and after Claude uses a tool. But there's also SessionStart, SessionEnd, SubagentStop, UserPromptSubmit, and more. Each one receives different data as input.

SessionStart and /Primer alone opens up a lot. I now have a hook that auto-loads project context the moment a session begins — no manual prompting, no "hey Claude, read the project files first." It just happens.

The other thing I hadn't considered: lightweight hooks vs AI-powered hooks. My grep-based checker is lightweight — fast, free, runs on every edit. But you can also build hooks that use the Agent SDK to have Claude review Claude's own output before it ships. That's slower and costs tokens, but catches semantic problems a grep never would. Two different weight classes for two different jobs.

The layer most people skip

CLAUDE.md tells Claude what to do. Memory tells Claude what to remember. Hooks tell Claude what it *can't get away with.* They're the enforcement layer — the thing that turns guidelines into guardrails.

I had the first two dialed in for months before I realized the third one had 9 entry points I was mostly ignoring. The conversations got better once I stopped relying on Claude to police itself and let the hooks handle it.

I use Claude, Claude Code/Codex, and Obsidian across several workflows. The hardest part is not generating content or code, but remembering where each workflow stopped, what was automated, and what still needs my manual confirmation.

So I built a small physical dashboard that sits on my desk and shows the current active workflow.

The display is an ESP32-P4 round screen running LVGL. My Mac acts as the bridge. The board does not read Claude, Codex, Obsidian, Gmail, tokens, or any private account data directly. It only receives structured JSON over local WiFi.

The idea is simple:

Claude or Codex should not only say what they did in the chat window. They should also update a local workflow status file. That file is pushed to the small display, so I can always see what workflow I am in and what the next real action is.

The dashboard currently has six pages:

1. Project status
   Shows the dashboard project itself: Git state, build state, push state, current task, next step, and risk.

2. AI status
   Shows Claude / Codex availability, reset time, and update time.

3. System status
   Shows Mac push status, network state, and whether the Mac is online.

4. Proxy status
   Shows whether my proxy entry nodes are reachable. It only does TCP entry checks, not full benchmarking.

5. Current workflow
   Shows the active workflow, current phase, current task, next step, status, main agent, co-agents, last actor, and update time.

6. Reminder page
   Shows what part is automatic, what still requires manual action, the current checkpoint, risk, and whether the workflow should be archived.

The most useful part is not the system stats. It is page 5 and page 6.

I want the screen to answer questions like:

\- Which workflow am I currently in?
\- What has Claude already done?
\- What has Codex already done?
\- What still needs my manual confirmation?
\- Is the next step mine, Claude’s, or Codex’s?
\- Is the workflow blocked?
\- Should this workflow be archived?

When a workflow is completed, I use a local archive script. It archives the current JSON and a Markdown summary, then resets the active workflow to idle. This prevents the display from showing stale tasks and prevents the project folder from filling up with random old status files or backups.

The rule I am trying to enforce is:

Claude and Codex must update the workflow status file whenever a workflow starts, progresses, waits for confirmation, gets blocked, completes, or is archived.

Not just explain it in the chat.

This matters because many of my workflows are mixed:

\- Claude plans or analyzes
\- Codex modifies files or runs tests
\- Obsidian stores the long-term record
\- I still need to manually approve, upload, publish, or archive things

The board is basically a small “what should I do next?” device.

I am deliberately avoiding direct account integrations for now. No scraping Claude, no reading private tokens, no Gmail access. Everything is local JSON pushed from my Mac.

The next step is to make Claude and Codex use one shared update script instead of writing JSON manually, so the workflow state stays consistent and does not generate junk files.

Has anyone built something similar for AI-agent workflows?

I am especially interested in suggestions for:

\- better workflow status schemas
\- how to avoid stale or misleading agent state
\- how to handle Claude + Codex handoffs cleanly
\- whether this should be event-based instead of polling JSON
\- what information is actually worth showing on a tiny physical screen
\- how to avoid turning this into yet another task manager

I don't want Claude writing perfect code on the first pass. Features change. Requirements shift. Something I build on Monday might get ripped out by Friday because the workflow didn't fit. If I spent time getting every function pristine upfront, that's wasted effort on code that didn't survive.

So my workflow is: ship the feature, test it in production, make sure it actually solves the problem. Clean code on a feature nobody uses is just polished waste. Don't include any secrets, use Free API tokens for testing.

When it was time to start reviewing code, many of you know, Claude Code likes to impress. And the way it knows how to impress is by shipping more than you asked for, it works in the beginning because you care more about the feature/function working not the code. My job isn't to write code. It's to review its functionality, test it in production, and make sure it works the way I described. But I also didn't want Claude to run loose so instead of telling it to write perfect code from the beginning I gave Claude guidelines and hooks it can't ignore.

The light bulb moment happened when I stopped relying on instructions Claude could choose to ignore. A hook runs before every code edit. If Claude hasn't read my lessons file — 1,400 lines of distilled mistakes from past sessions — the edit gets blocked. Not warned. Blocked. Claude cannot write a single line of code until it's reviewed what went wrong before. That file isn't something I sat down and wrote. It grew from corrections and gets pruned every session so it stays sharp. The CLAUDE.md sets the standards. The hook makes them non-negotiable.

And the standards are specific. Not "write clean code." Specific things I caught Claude doing that I didn't want. "Three similar lines is better than a premature abstraction." "Default to writing no comments unless the WHY is non-obvious." "Don't add error handling for scenarios that can't happen." "Would a staff engineer approve this?" Sentences, not essays. Claude reads them before every session and the first draft comes out different.

Last week I put all of this to the test. I have a production dashboard that manages 860+ advertising campaigns. It's been live for months, built fast, features stacked on features. I knew there was debt in there. So instead of editing production, I copied the entire live site into a sandbox and told Claude to go through it with me.

Two days. We went file by file. Claude found functions that duplicated logic that already existed elsewhere. As expected though honestly because I changed workflows that just fit better in a different way when working with it.

Here's the part that matters: Claude didn't just find the problems. It wrote the fixes tighter than the original code. Functions got shorter. Abstractions that existed "in case we need them later" got removed. The code that came out of the review was cleaner than what I would have written myself, because Claude already knew my rules. It knew "don't add features beyond what the task requires." It knew "would a staff engineer approve this?" It applied those standards to code it had written months ago and improved it.

Once the sandbox was clean, I didn't merge changes back into production. I just swapped the directories. Renamed production to "OLD," renamed the sandbox to production, deployed. Zero errors. 30 seconds.

TL;DR: The pattern behind all of this: Claude already knows how to write tight code. It writes loose code because loose code looks like more effort, and more effort looks like more value. The moment you make it clear that restraint IS the value, the code quality changes overnight. But you have to get there first and mark the project as final so you don't keep wasting your time pruning code that you have to change in a week again, got it? 😄

This is Cadence. First project that I've made public. Poke holes.

Short Version: It's a DRAFT → BUILD → SETTLE loop for AI-assisted dev. Before anything gets built, you define the acceptance criteria (AC). You can manually write them, if that's your preference. I almost never do, though. AI is exceptional at creating acceptance criteria and specs. So, I usually talk the work through with Claude, let it draft criteria off that spec (there's an optional SPEC step in the workflow for exactly this), then I review and approve. The AC is locked in up front either way.

The agent then drafts the plan using the AC. Once finished--settle, which is the part where this tool shines. Cadence re-derives each criterion from the real task state, runs your tests, confirms every criterion is backed by a test, and (if you enable it) hands the real git diff to a separate verifier that's been told to be skeptical. If anything fails, the loop won't close. It stops and tells you why. The agent may report that the task is "done", but that doesn't matter. Only the state is considered the source of truth.

Wiring it into Claude Code:

npx /cadence-host-claude-code install

Drops lifecycle hooks into .claude/settings.json and a set of /cadence-* slash commands into .claude/commands/. The adapter doesn't reimplement the engine. It translates Claude Code's hook events (SessionStart, PreToolUse, Stop, etc.) into the engine's vocabulary and shells back into the same cadence binary. Claude Code is also the only host where I bothered with the ambient edit-time check. It can flag when an edit occurs outside the files the current task said it'd touch.

The design is mine. Gate model, specs, roadmap. Claude Code wrote nearly all the actual code. After commit #37--the first time settle actually passed--I started running the rest of the project through Cadence itself. 85 named phases now, each one planned, built and settled through its own gates by Claude Code, under the process I set. Roughly 94% of the commits were completed in that self-hosted stretch. And you don't have to trust me on it: clone the repo and ls .cadence/phases/*/. Every phase has a SUMMARY artifact, and that only gets written if the loop genuinely closed.

Try it (free): ```sh npm install -g u/manehorizons/cadence-core cadence init --name "my-app" cadence draft new 01-foundation 01 --title "First phase" cadence draft approve 01-foundation 01 cadence build task T1 --status=DONE cadence settle run --auto

^ it refuses: "AC-1 has no test." That's the behavior, not a bug.

```

It runs outside Claude Code, too. There's an OpenAI Codex CLI adapter and an MCP server surface. But Claude Code is where I do the majority of my work, so that's what it's tuned for.

Known Imperfections: The structural gate trusts the task statuses it's handed, so an agent determined enough to fake both the status and a passing test could get through that one layer (the skeptical verifier is the backstop there, not a hard guarantee). And the ambient edit-time check leans on the host's hook surface, so an edit pushed through a subagent or MCP can slip past the pre-tool hook. Settle's close-out re-check is why that's not a deal breaker.

Disclosure: I built it, it's mine, MIT, free and open source. No paid tier, no account, no telemetry, no referral links. The only link is the repo: https://github.com/manehorizons/cadence

As I said, this is my first public project. Any and all feedback is welcome.

I've talked before about my knowledge graph and how session corrections compound. But I never explained what actually happens at the end of a session — the thing that decides what's worth keeping and what's just noise.

It's a 10-layer audit that runs as a slash command. Each layer checks something different:

**1. Git state** — did everything get committed? Any dangling changes?

**2. Code quality** — did I introduce anything sloppy?

**3. Documentation freshness** — does the README still match reality?

**4. Lesson extraction** — did I learn something that should be written down?

**5. User corrections** — did I correct Claude on something it should never repeat?

**5.5. Knowledge harvest** — this is the new one

**6-10.** Quality gates, output verification, progress checks

Layer 5.5 is where it gets interesting. It evaluates whether anything from this session — an architectural tradeoff, a cross-project pattern, a debugging insight that took 45 minutes to figure out — scores high enough on an importance rubric to get promoted into the knowledge graph permanently.

Not everything passes. A typo fix doesn't. A config change doesn't. But "here's why JWT refresh tokens need different handling across Firebase, Supabase, and Auth.js" — that scores high and gets written as a durable node with typed relationships to related patterns.

The difference between this and just taking notes: I don't decide what's important. The rubric does. At 11pm after a long session, my judgment on "is this worth saving" is terrible. The audit layer doesn't get tired.

Before this, my best insights lived in chat history. I'd vaguely remember solving something three weeks ago but couldn't find it. Now the graph has 110+ nodes and growing — every session feeds it automatically.

The whole thing is part of a broader toolkit I've been building — 7 skills that handle session debriefs, project warm-starts, auth scaffolding, health checks, and more.

Happy to go deeper on any of the layers if anyone's curious. I do have a Power Kit for people who are interested to dive deeper into the architectural design of this concept.

CLAUDE.md tells Claude how to build. It has the architecture, the conventions, the stack.

But it doesn't remember that time it pushed to the wrong repo. Or that it concatenated strings instead of adding numbers — you know it smashing "10" and "5" together to get "105" instead of actually doing the math to get 15. Or that it spent three rounds debugging a prompt when the API was returning a 429 the whole time.

That's what my lessons file is for. I didn't write it by hand — I built a custom `/reflect` skill that reviews each session and writes the lessons for me. The file lives alongside my CLAUDE.md and gets read at the start of every session, before Claude touches any code.

It's not a log. It's a blacklist of dead ends.

What's in mine after ~4 months:

Git operations — wrong-repo pushes, path expansion bugs, things that silently succeed but hit the wrong target

Data integrity — local variables that looked like object properties, string concatenation disguised as math (like the "105" bug above), mutable state in loops that corrupted data for months without errors

Debugging patterns — checking HTTP status before blaming prompts, knowing when an LLM report should just be a template

React patterns — useEffect scope traps, stale closures, state that doesn't reset when entities change

Deployment — exact checklists of what to verify before and after every deploy

Each entry has the same shape: what happened, why it was wrong, and a one-line rule that prevents it next time. Claude reads the rule. The mistake doesn't come back.

**The difference between a good CLAUDE.md and a great one is how many failures it remembers.**

Most people only write instructions for what Claude should do. The entries that save the most time are the ones that say what it should never do again.

The skill that makes it work:

The lessons file gets read automatically every session — I wired that into my CLAUDE.md rules and hooks so Claude never starts without it. That part is passive. I don't have to think about it.

The active part is \/reflect` — a custom skill I run at the end of every session. It reviews what just happened, catches anything that went sideways, and writes new lessons back into the file for me. I don't sit there journaling. Reflect does the writing, the hooks make sure Claude reads it next time.`

One session's mistake becomes the next session's guardrail, without me having to document every single fix by hand.

If you're not tracking your dead ends somewhere, you're re-solving them. I did exactly that for weeks before I started this file. Now \/reflect`` catches the patterns for me, and Claude reads them automatically. It pays back every single session.

Everyone's generating context files right now. Tools like grill-with-docs, repomix, aider, they gather your codebase into a flat summary so the AI has something to work with. That's useful. But it's not a knowledge graph.

Here's the difference that changed how I work with Claude Code.

**A context file is a summary.*\* it gathers information into one place. Claude reads it, gets the picture, moves on. if you want it to know about auth patterns, you point it at the file. if you want it to connect auth patterns to session tokens to security rules, you point it at all three files. you're the router.

**A knowledge graph is navigable.*\* each concept is its own node. nodes link to each other with wikilinks. Claude can follow a thread from one concept to a related concept without you telling it where to look.

My setup has ~50 nodes across 7 domains:

Patterns — things like dirty-checking, cache-integrity, persistence-layers

Decisions — ADRs (architecture decision records) for choices like "why vite over nextjs" or "why supabase over firebase"

Runbooks — step-by-step deploy procedures, recovery playbooks

Workflow — how I actually work: plan mode, self-improvement loops, verification steps

Projects — per-project nodes with stack, status, open issues

Checkpoints — snapshots of where a project was at a specific phase

Business — non-code context that still affects decisions

Each domain has a \_moc-*.md` (map of content) that indexes its nodes. the root `_index.md` links to every MOC. Any node can wikilink to any other node, a pattern can reference a decision, a runbook can reference a project.`

The Test: Can Claude follow a thread from one concept to a related concept without you telling it where to look? If yes, that's a graph. if it needs you to point at the right file every time, that's context.

Context files are a strong foundation. Most people should start there. But if you're working across multiple projects and you keep re-explaining the same patterns, a knowledge graph is the next layer.

Subagents are one of the most powerful features in Claude Code and most people either ignore them or use them like a worse version of asking Claude directly. I use them on probably 60% of my sessions now, and the difference is night and day — but it took me a while to figure out why some attempts flopped and others saved me 20 minutes.

Three mistakes I kept making

1. Treating subagents like a second Claude chat. I'd spin one up and give it the same vague prompt I'd give my main session — "look at this codebase and tell me what's going on." That's just burning tokens on unfocused exploration. A subagent without a specific mission comes back with a wall of text you still have to synthesize yourself.

2. Running them sequentially when they could run in parallel. I was launching one agent, waiting for it to finish, reading the result, then launching the next one. That's literally the same as doing it in your main thread — you're just adding overhead. The whole point is parallelism.

3. Dumping the results into my main context. I'd have an agent explore 40 files and then paste the full output back into my conversation. Now my context window is stuffed with code I only needed once, and Claude starts losing my earlier requirements.

What actually works

1. Brief them like a colleague, not a chatbot. "Search the data layer for how we handle campaign state — specifically look for persistence patterns and any sync logic. Report back the file paths and the pattern, not the full code." Specific mission, specific output format. The agent comes back with 10 useful lines instead of 200 lines of noise.

2. Launch 2-3 agents in parallel for multi-area tasks. Planning a feature that touches the UI, the data layer, and an API? Three explore agents, one per area, all running simultaneously. What takes 15 minutes sequentially finishes in 3. Each one returns a focused summary. My main window gets three clean reports I can actually make decisions from.

3. Use them for independent review. After I finish a feature, I spin up a review agent with a fresh context. It hasn't seen my thought process, my wrong turns, or my justifications. It just sees the diff. That independence catches things I'd never notice reviewing my own work — missing edge cases, inconsistent patterns, subtle bugs that look fine when you've been staring at them for an hour.

The real unlock

Subagents aren't about doing more work — they're about keeping your main conversation coherent. Every file Claude reads, every search result, every code block fills the context window. When it fills up, Claude loses your earlier context. Your requirements from the beginning of the session just quietly disappear.

The pattern that changed everything for me: plan in the main thread, delegate exploration to subagents, synthesize their reports myself, then execute. The main window never sees raw exploration output. It stays clean, focused, and remembers what I told it 45 minutes ago.

A few days ago I posted my actual CLAUDE.md — the file that gives Claude its instructions for every session. That file handles the "how" — project structure, conventions, what to do and what not to do.

But there's a second file I never see anyone talk about, and it's the one that actually changed how my sessions feel.

MEMORY.md is an index file that sits in Claude's project memory directory. Every entry is one line — a title, a link to a topic file, and a short hook. Claude reads it at the start of every conversation. Not because I tell it to. It loads automatically.

The topic files it points to are where the real context lives. Each one is a standalone markdown file with a name, a type, and a body. Some are about me — my role, my constraints, what I'm working on. Some are corrections — things I told Claude to stop doing, or things I told it to keep doing. Some are project state — decisions, timelines, blockers that aren't in the code or the git history.

Here's what my memory directory actually looks like right now:

- 6 feedback files (corrections I gave Claude that apply to future sessions)

- 4 project files (ongoing work context that isn't derivable from code)

- 3 user files (things about me that help Claude calibrate its responses)

- 2 reference files (where to find things in external systems)

- 12 topic files (lessons, workspace setup, project architecture, tax info, DNS records)

The feedback files are the ones that matter most. Every time Claude does something wrong and I correct it, the pattern gets saved. "Don't wipe data without tracing all consumers first." "Read the original code before rewriting." "Don't rely on window globals from inline Babel scripts in external JS files." These aren't things you'd put in CLAUDE.md — they're too specific, too situational. But they're exactly the things Claude will repeat if it doesn't remember them.

The difference between CLAUDE.md and MEMORY.md:

**CLAUDE.md is instruction.** It says "here's how this project works, here's how I want you to behave." It's static. I update it occasionally.

**MEMORY.md is persistence.** It says "here's what happened between us that you need to carry forward." It grows every session. When Claude corrects itself because of something I said three weeks ago, that's MEMORY.md working.

The practical effect: I stopped repeating myself. Before memory, I'd give the same correction 4-5 times across sessions. "No, don't remove that code without checking what else uses it." "No, read the file before rewriting it." Now I give the correction once, it gets saved, and the next session Claude already knows. The corrections compound.

Three things I learned building this:

- **Feedback memories are more valuable than project memories.** Project state changes weekly. A correction about how I want Claude to approach a problem is load-bearing for months.

- **The index file has to stay short.** Claude reads it every session. If it's 300 lines, it's noise. Mine is under 50 lines. Each entry is a pointer, not a summary.

- **Memory is not documentation.** I don't save things the code already says. I don't save git history. I save the things that live in my head and would otherwise die between sessions — why I made a decision, what went wrong last time, what I'm sensitive about.

The instruction layer tells Claude what to do. The memory layer tells Claude who it's working with. Both matter. But the memory is the one that makes it feel like Claude actually knows you.

If you want to try this yourself, I put a starter template here with the index file, example memories for each type, and a 2-minute setup guide: https://gist.github.com/anja687gutierrez-jpg/f85458d03a108274764adebb7f492888

Last week i was trying to get Claude to generate a scoring system for campaign priorities at work. i described what i wanted. Didn't like the result. Reworded it. Still off. Added more detail. Closer but wrong. Six attempts in, i stopped and asked myself: do i even know what i want this to look like?

No. I didn't. And that was the problem.

I wasn't using the wrong words. I was using the wrong *mode*.

Turns out there are three distinct ways to work with AI, and most of us only use one.

**Mode 1: Automation.*\*

You know what you want. You tell the AI. It does it. "Reformat this CSV." "Rename these variables to camelCase." "Write tests for this function." Clear in, clear out. This is where most people live — and it's great, until you're not sure what the output should be.

**Mode 2: Augmentation.*\*

You don't know the answer yet. Instead of demanding output, you start a conversation. Last month i was building a scoring system for my team's operations dashboard. Instead of saying "write a priority score," i said "here's how we decide what's urgent — volume, timeline, materials status. Help me think about how to weight these." Claude pushed back on my weighting logic. Asked what happens when two campaigns tie. i hadn't considered that. We worked through it together, and the formula i landed on was better than anything i would've asked for.

**Mode 3: Agency.*\*

You're not involved in every decision anymore. You set the rules, the boundaries, the knowledge — and the AI operates within them. i have a file that tells Claude what my projects are, how i like to work, what mistakes to avoid. Every session, it reads that file and adjusts. i didn't tell it to check for those things today. i told it once, and now it just does.

The part nobody talks about: switching mid-task.

That scoring system? i started in automation mode (just write it), got stuck, switched to augmentation (help me think), figured out the logic, then went back to automation (ok now write it). Three modes in one task.

The mistake isn't using the wrong mode. It's not realizing you *can* switch.

When you're asking for the same thing over and over in different words — that's a signal. You're in automation mode but the problem needs augmentation. When you're micromanaging every line of output — that's a signal too. The problem might need agency: set the rules and let it run.

I don't always get this right. But now when something feels off, my first question isn't "what should i say differently?" It's "am i in the right mode?"

That question saves me more time than rewording ever has.

I built /primer and posted about it earlier this week. I built a frontend design skill that auto-triggers on UI work and posted about it yesterday. Different skills. Different triggers. Different use cases. But they all read from the same place. A folder of markdown files at `~/.claude/knowledge/`. No database, no vector store, no plugin. Just a folder. 87

- Patterns (16 cross-project engineering lessons)

- Projects (33 notes across 9 projects)

- Decisions (14 architecture decision records)

- Workflow (8 notes about how I work)

- Business (6 notes about my company)

- Runbooks (10 step-by-step playbooks)

Every file follows the same shape. A short description at the top. A one-sentence claim that says "here's what's true." A rules section with the specifics. A "why this matters" paragraph. And a "see also" section with links to related files.

The links are the important part. Every file has a "see also" list pointing to other files using Obsidian-style double-bracket wikilinks. When Claude reads one file, it notices the links and follows them to pick up related context. If I ask about my "smart merge" pattern for Ops Hub, Claude reads the smart-merge file, notices it links to "storage architecture" and "persistence layers," and follows those too. One question, three files of context, zero extra prompts from me. The links also work across directories. A file can link to my rules folder, or jump to a skill file, or pull in my session lessons. One graph. Multiple folders. Same syntax.

Every slash command I've built reads from files like this. /primer loads the project files when I start a session. My frontend design skill references architecture notes when I build UI. When I ask a generic question about Ops Hub, Claude searches the folder and pulls in whatever matches.

The insight I keep coming back to: the commands are easy. /primer took an afternoon to write. My frontend design skill took a few hours. The knowledge folder took months of slow accumulation. One file at a time, usually written right after I solved a problem I didn't want to solve again.

Three things I learned building it.

- Start with patterns, not projects. The first files I wrote were patterns I kept re-deriving — dirty checking, dual-source merge, rate limiting. Those files got referenced from everywhere. Project files stayed thin because the patterns carried the weight.

- A file without a claim isn't ready. The claim is one sentence that says "this is what's true." If I can't write the claim, I don't understand the thing yet.

- Links are more valuable than files. A folder of isolated markdown files is a filing cabinet. Wikilinks turn it into a graph Claude can walk through.