asynthlogr

Async logging of synthetic thought — the reasoning behind AI-agent decisions, captured without slowing anything down.

What it does

• Logs decisions (ADR-style: context, options considered, options discarded and why, final decision, rationale, decision-maker) and freeform info notes, per chat thread.
• Logs every subagent call's raw prompt/tools/output separately from the distilled decision log.
• Non-blocking: nothing you or your agents do waits on a log write.
• Organized per repo, per chat thread, in a basic-memory vault.
• Links straight back to the code: Cursor, VS Code, and GitHub links per file reference, resolved automatically via git/gh.
• Tracks which step of your research → clarify → propose → discuss → plan flow you're on, per thread.
• Records the Claude Code session ID of every thread and the agent ID of every subagent run (straight from Claude Code's hooks), so you can resume either conversation later: claude --resume <session_id>.
• Never makes you wait on a subagent: each run's output note starts as a placeholder with the agent ID, resume command and transcript path, so a run whose output never got logged can still be recovered.
• Talks to you like a human (ADHD-optimized formatting, see skills/i-have-adhd/) for anything addressed to you; strict machine templates for everything agent-to-agent.
• Writes vault notes as correct, properly-wikilinked Obsidian markdown (see skills/obsidian-notation-expert/, skills/obsidian-node-link-expert/) — the vault is meant to be browsed in Obsidian, Graph View included, not just read as flat text files.

Requirements

• Claude Code with subagent + hooks support
• basic-memory — REQUIRED. Every piece of information this tool logs is written through basic-memory; there is no fallback storage mode. install.sh detects it one of two ways, preferring an already-running Docker deployment:
  • Docker mode: if the official ghcr.io/basicmachines-co/basic-memory image is already up, install.sh hooks onto it — registering its MCP endpoint (http://localhost:<port>/mcp, SSE or HTTP, as the container runs it) with Claude Code and creating the asynthlogr project through that same MCP endpoint. It never starts Docker, never starts a container, and never execs into one.
  • CLI mode: otherwise, it installs the basic-memory CLI (via uv) and registers its MCP server with Claude Code automatically, same as before — see basicmachines-co/basic-memory.
• uv (needed to install basic-memory if it isn't already present and no Docker deployment is found)
• git + gh CLI (for resolving commit/PR links)
• jq — used by the hooks and the report script at runtime, and by install.sh to merge into an existing .claude/settings.json
• Obsidian is an optional viewer on the same directory basic-memory manages — not itself a requirement.

Install

./install.sh /path/to/your/repo
# hooks onto an already-running basic-memory Docker container if one
# exists; otherwise installs the CLI if missing and registers its MCP
# server if needed. Defaults to basic-memory's own storage root
# (~/basic-memory), or the running container's actual mount in Docker
# mode, if you don't pass one:
./install.sh /path/to/your/repo --basic-memory-root /path/to/basic-memory

See docs/architecture.md's "basic-memory: CLI mode vs. Docker mode" section for exactly how detection works and what it does in each mode.

asynthlogr does not get an arbitrary directory of its own — it lives at <basic-memory-root>/asynthlogr and is registered as its own basic-memory project named asynthlogr, alongside whatever other projects you already have in basic-memory.

See docs/architecture.md for exactly what the installer does and which files it creates vs. appends to.

Usage

Nothing to invoke manually most of the time — logging happens as you work through your normal research → clarify → propose → discuss → plan flow. To log something that isn't a decision: just say "log this: ...".

Daily reports are manual: run /asynthlogr-report for today so far, /asynthlogr-report --date 2026-09-25 for a given day, or /asynthlogr-report --catch-up to fill in every finished day that's missing one. Each writes reports/<date>.md into the vault.

Vault layout produced — see docs/vault-layout.md for full detail:

<vault>/<repo>/<thread>/<thread>.md
<vault>/<repo>/<thread>/agent-use-tracking.md
<vault>/<repo>/<thread>/subagents/<run>/output.md
<vault>/<repo>/<thread>/subagents/<run>/agent-use-tracking.md

Testing

bats tests/unit/          # layer 1
tests/docker/run.sh       # layer 2 (debian:bookworm-slim)

See tests/README.md for what each layer covers and what it doesn't.

Documentation

• docs/architecture.md — problem statement, the 5-step flow this observes, core architectural principles, the race-condition fix, the placeholder output notes, the human/machine communication boundary
• docs/vault-layout.md — full vault directory structure
• docs/decision-entry-format.md — the decision/info entry templates
• docs/subagent-run-format.md — the delegation template, output.md, and both tracking-file formats
• docs/reports-design.md — the daily report: format, generator, trigger
• docs/known-limitations.md — what this system cannot guarantee
• docs/open-items.md — unresolved implementation details a coding agent should verify before/while building this

Known limitations

• Model name / context-window % are self-reported by the orchestrator, not measured — Claude Code has no API for this. Always labeled unverified in the log.
• A run whose output was never logged (session ended first) keeps only its placeholder note; you recover the output from the subagent yourself, using the resume command or transcript path it lists.
• Thread naming happens once per session; it isn't retroactively editable by decision-logger.

See docs/known-limitations.md for the full list with explanations.

Files this installer touches

• Creates or appends to: AGENTS.md, CLAUDE.md, .claude/settings.json
• Creates: .claude/agents/*.md, .claude/hooks/*, .claude/skills/*/, .claude/asynthlogr/formats/*, .claude/asynthlogr/bin/*, .claude/asynthlogr.config.json
• Registers basic-memory as a Claude Code MCP server (local scope, for the target repo)

License

MIT (includes vendored i-have-adhd skill, MIT, https://github.com/ayghri/i-have-adhd)