homestead-memory Logs Claude Tool Calls

homestead-memory is a small MIT-licensed Python project from fuckbigtech-ai that records Claude Code tool calls into a local, hash-chained audit file. It deals with a boring but painful failure mode: the agent says the work happened, the tool returned success, and nobody has a trustworthy record of what actually ran. Hooks in Claude Code, Anthropic's coding agent, are commands that run at lifecycle events such as before or after a tool call; this project uses that boundary to make agent work reviewable. The takeaway is simple: log tool calls when you need evidence, not because every session deserves a black box.

It is also a useful answer to what are hooks in Claude Code: they are not magic memory, they are programmable checkpoints around agent activity. In this case, the checkpoint writes an evidence trail. The Show HN detail that made developers look twice was the claim of logging every tool call at about 124ms per call, which is small enough to test and big enough to measure.

Read the project as a flight recorder

homestead-memory is not trying to be another chat transcript. It records the agent's tool activity in a local file, with each entry linked to the previous entry by a hash.

That matters because tool calls are where agent work becomes real. A chat answer can say “I updated the migration,” but the tool call says whether the file was opened, edited, tested, or left alone.

A concrete Claude Code workflow might look like this: Claude proposes a schema change, runs Edit, runs Bash for tests, and then says the branch is ready. Without a tool-call record, review starts from trust. With a hash-chained record, review starts from evidence.

The trap is treating the log as proof that the code is correct. It is not. It is proof that a sequence of recorded events has not been quietly edited, deleted, or reordered without detection.

As of September 2026, the repository is tiny: mainly Python, MIT licensed, last pushed on 2026-09-09, and listed with one GitHub star in the source signal. That smallness is part of the story. The project is less a platform than a sharp experiment: can a local file make agent work easier to audit?

Care about the hash chain, not just the log

The interesting part is the chain. Each record depends on the record before it, so changing one entry breaks the entries after it.

That is why homestead-memory calls itself tamper-evident rather than tamper-proof. Someone can still delete a file, bypass a hook, or run an agent outside the instrumented path. But if a recorded chain is edited after the fact, verification should catch the break.

The README also points at a second phase: signing. A signature helps catch the more ambitious attack where someone rebuilds the whole chain from scratch and pretends it is the original.

This is the same distinction developers already understand from lockfiles and checksums. The checksum does not make the package safe. It tells you whether the thing you received is the thing someone claimed to send.

The objection developers raised in spirit is fair: “Why do I need this when I can just scroll back through the terminal?” Because terminal scrollback is a convenience. It is not an artifact you can hand to someone skeptical and ask them to verify.

Put the hook at the boundary you would review

The clean use of Claude Code hooks is to log the boundary where intent becomes action. For homestead-memory, that means before and after tool calls, especially tools that mutate state or touch external systems.

Start with a narrow hook boundary. Bash, Edit, Write, and MultiEdit are usually more interesting than a harmless read. If your Claude Code workflow uses MCP servers for GitHub, issue trackers, or databases, write down which tool calls are allowed to appear in an audit log and which ones might include secrets.

Here is a small hook shape you can adapt after checking the current Claude Code hooks documentation and the homestead-memory README. The command is intentionally local, so you can review what gets written before pointing it at real work.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/record-tool-call.py pre"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/record-tool-call.py post"
          }
        ]
      }
    ]
  }
}

The trap is logging everything before you know what “everything” contains. Tool arguments can include tokens, file paths, customer data, or private repository context. A good first hook redacts aggressively and records only the fields needed for review: event type, tool name, timestamp, working directory, command summary, exit status, and hash pointer.

If your repository already has concise CLAUDE.md instructions, keep them boring: “Do not paste secrets into tool arguments” is useful. But do not ask memory to do the job of evidence. The hook is the receipt.

Try it safely on one real command

The project gives a low-friction demo path for people who do not want to install into a repo immediately:

uvx --from homestead-memory hsm watch --demo

That is the right first move. Run the demo, inspect the local file, then intentionally tamper with a record and verify that the watcher reports the break. The point is to feel the failure mode before you wire anything into your daily Claude Code workflow.

For a real repo, use a boring branch and a boring task. Ask Claude to update one test fixture, run one command, and stop. Then compare three artifacts: the code diff, the terminal output, and the homestead-memory record.

A safe first experiment:

• Pick a non-secret repo and a branch you can throw away.
• Log only Bash at first, not every hook type.
• Run one command Claude suggests, such as pytest tests/test_parser.py.
• Verify the record before and after you edit one line by hand.
• Check whether the extra latency is acceptable for your loop.
• Delete the experiment if the log captures secrets or noisy payloads.

This is where the 124ms claim should be treated like an invitation, not a universal benchmark. On a long test run, 124ms is invisible. In a tight loop with many small tool calls, it can become annoying.

This also fits the broader Claude Code conventions topic: teams often argue about trust in agent output, but the better question is what evidence a reviewer gets. We keep related Claude Code workflow notes under the related training topic, and the inter-agent version of the same problem shows up in crew Lets Claude, Codex, and opencode Talk.

Know when the receipt is overkill

homestead-memory is a good fit when the cost of a false success is higher than the cost of logging. Release scripts, database migrations, generated client updates, infra changes, and MCP calls to external systems are all plausible candidates.

It is probably overkill for disposable exploration. If you are asking Claude to explain a file, sketch a refactor, or grep a repository, a hash-chained evidence log may add ceremony without changing the outcome.

A simple fit table is enough:

The trap is confusing auditability with permissioning. A log can tell you what happened. It should not be your only control over what is allowed to happen.

For sensitive MCP work, pair the log with a permission note: read-only by default, write actions require explicit approval, and secret-bearing responses are not persisted. That is less dramatic than “record every tool call,” but it is the boundary that keeps the record useful.

Common questions

• What are hooks in Claude Code, practically?

  Claude Code hooks are commands that run at defined moments in the agent lifecycle, such as around tool use. They let you record, block, format, or route events outside the model. homestead-memory uses that idea to capture both phases of tool activity into a local hash-chained record.

• Where is the Claude Code hooks documentation?

  The official Claude Code hooks documentation is the right place to check current event names, hook types, matcher behavior, and JSON structure. Use it before copying any snippet from an article, including this one. Hook surfaces change faster than review habits, and the docs are the contract.

• Does homestead-memory prove Claude did the right thing?

  No. homestead-memory helps prove that a recorded sequence of tool calls has not been silently altered. It does not prove the code is correct, the command was safe, or the agent made a good decision. Treat it as review evidence, not as a correctness oracle.

• Is 124ms per call fast enough?

  Sometimes. The Show HN signal framed the project around roughly 124ms per logged tool call, which is likely fine for heavyweight actions like tests or deploy checks. It may feel expensive for tiny, frequent calls. Measure it in your own repo before making it part of a default workflow.

• What should I avoid logging first?

  Avoid secret-bearing payloads first: environment dumps, authentication headers, raw MCP responses, customer data, and generated files with private content. Start with command metadata and exit status. Add richer payloads only after you have redaction, retention, and a clear reason to keep them.

Best ways to use this research

• Best for: Claude Code users who need a verifiable record of agent actions during risky local work, especially commands, edits, and external tool calls.
• Best first artifact: A narrow PreToolUse and PostToolUse hook around Bash, tested on a throwaway branch with one command.
• Best comparison angle: Compare chat transcript, terminal scrollback, and hash-chained tool log. The value appears when those three disagree.
• Best caveat: Tamper-evident logs are not permission systems. Keep MCP permissions, approvals, and secret redaction separate from the audit trail.

Further reading

• Claude Code — hooks
• Anthropic — Claude Code product page
• homestead-memory — source

Try the smallest honest version

Run the homestead-memory demo, break the chain on purpose, and decide whether the receipt would have helped in your last confusing Claude Code session. If yes, add one narrow hook around one risky tool and review the log before expanding it.

One methodology lens

One useful way to read this through our methodology is the Plan step: delegate first-pass decomposition and dependency mapping, review the sequencing and assumptions, and keep ownership of scope and priorities. If that split is still fuzzy, the workflow usually is too.