{"id":50789976,"url":"https://github.com/loresuso/agent-history","last_synced_at":"2026-06-12T10:30:24.222Z","repository":{"id":358895496,"uuid":"1243469272","full_name":"loresuso/agent-history","owner":"loresuso","description":"Don't lose your coding agent useful commands!","archived":false,"fork":false,"pushed_at":"2026-05-19T13:46:26.000Z","size":25,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-19T16:10:33.836Z","etag":null,"topics":["coding-agent","shell"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/loresuso.png","metadata":{"files":{"readme":"README.md","changelog":"history.go","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-19T11:21:06.000Z","updated_at":"2026-05-19T13:50:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/loresuso/agent-history","commit_stats":null,"previous_names":["loresuso/agent-history"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/loresuso/agent-history","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loresuso%2Fagent-history","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loresuso%2Fagent-history/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loresuso%2Fagent-history/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loresuso%2Fagent-history/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/loresuso","download_url":"https://codeload.github.com/loresuso/agent-history/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loresuso%2Fagent-history/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34240813,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["coding-agent","shell"],"created_at":"2026-06-12T10:30:23.734Z","updated_at":"2026-06-12T10:30:24.217Z","avatar_url":"https://github.com/loresuso.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# agent-history\n\nA Claude Code plugin that captures every Bash command a coding agent runs\nand, at session end, flushes those commands into your native shell history\nfile. So your normal `Ctrl+R` finds them, like commands you typed yourself.\n\nBuilt for Claude Code today; designed so other coding agents can be added\nlater.\n\n## Why\n\nCoding agents run Bash commands in a subprocess, so they never land in your\nshell history. You can't `Ctrl+R` to recall that one useful `gh` or `gcloud`\ninvocation the agent figured out, and there's no easy way to review what the\nagent actually did during a session.\n\nThis plugin captures every Bash tool call to an audit log, then batches the\nsession's commands into `~/.zsh_history` (or your shell's equivalent) when\nthe session ends.\n\n## Install\n\n### 1. Required zsh setup\n\nIf you use zsh, **add this line to your `~/.zshrc`**:\n\n```sh\nsetopt INC_APPEND_HISTORY\n```\n\nWhy: zsh's default save-on-exit can rewrite `~/.zsh_history` from a stale\nin-memory snapshot, clobbering anything other processes (like this plugin)\nwrote since that shell started. `INC_APPEND_HISTORY` forces every save to be\nan incremental append. Pair it with `share_history` (already set by\noh-my-zsh) for cross-terminal history that doesn't lose external writes.\n\nAfter editing `.zshrc`, **close every existing terminal window** and open a\nfresh one — running shells still operate under whatever options they had at\nstartup.\n\n### 2. Install the plugin\n\nRequires Go on `$PATH` (used by the SessionStart bootstrap script).\n\n```\n/plugin marketplace add git@github.com:loresuso/agent-history\n/plugin install agent-history@loresuso-plugins\n/reload-plugins\n```\n\nThe next time a Claude Code session starts, the binary builds; commands\ncaptured during the session are flushed to your shell history when the\nsession ends.\n\n## How it works\n\nThe plugin registers three hooks:\n\n- **`SessionStart`** runs `scripts/bootstrap.sh`, which builds the bundled Go\n  binary into `bin/agent-history` if it's missing or older than the sources.\n- **`PostToolUse`** on the `Bash` tool runs `scripts/run.sh`, which forwards\n  the hook JSON (on stdin) to `agent-history run`. That writes a structured\n  JSONL record to `$XDG_DATA_HOME/agent-history/log/\u003csession-id\u003e.jsonl`.\n- **`SessionEnd`** runs `scripts/flush.sh`, which calls `agent-history flush`.\n  That reads the session's JSONL log and appends every captured command to\n  your shell history file in a single batched write.\n\nPer-session JSONL files mean **multiple concurrent Claude sessions don't\ncollide on writes** — each writes to its own file.\n\n## Paths\n\n| What        | Location                                                |\n|-------------|---------------------------------------------------------|\n| Config      | `$XDG_CONFIG_HOME/agent-history/config.json` (default `~/.config/agent-history/`) |\n| Audit logs  | `$XDG_DATA_HOME/agent-history/log/\u003csession-id\u003e.jsonl` (default `~/.local/share/agent-history/log/`) |\n| Shell hist  | Detected from `$SHELL` (zsh / bash / fish); overridable in config |\n\nEdit the config file by hand to change the shell, history path, or set a\nfilter regex (commands matching the regex are skipped on capture).\n\n## Audit a session\n\n```\nbin/agent-history tail -s \u003csession-id\u003e | jq\n```\n\nSession ids match the `\u003cid\u003e.jsonl` filenames in the log directory.\n\n## Recover a session that never flushed\n\nIf Claude Code crashed or was force-killed, `SessionEnd` may not have fired\nand the session's commands won't be in your shell history. The audit log is\nstill complete, so:\n\n```\nbin/agent-history flush -s \u003csession-id\u003e\n```\n\nwill append everything captured in that session to your shell history file.\n\n## Diagnostics\n\n`scripts/flush.sh` writes one line per invocation to\n`/tmp/agent-history-flush.log` (timestamp, before/after file size, exit\ncode, payload length). If a session's commands don't appear in your shell\nhistory after `/exit`, that log tells you whether SessionEnd actually fired\nand how many bytes the flush wrote — separately from whether those bytes\nsurvived subsequent zsh saves.\n\n## Security\n\nThe plugin captures Bash commands **verbatim**. Your shell history and the\naudit log will contain whatever the agent ran — including secrets that\nappeared inline (`export TOKEN=...`, `Authorization: Bearer ...`, etc.).\nSame trust model as your normal `~/.zsh_history`.\n\nFiles are written mode `0600`, directories `0700`. Don't paste them into\nchat, screenshots, or pastebins. Don't sync them to shared cloud storage.\n\n## Caveats\n\n- **Shell history shows up at SessionEnd, not in real time.** Commands land\n  in `~/.zsh_history` when the Claude session exits, not while it's still\n  running. Use `agent-history tail -s \u003cid\u003e` against the audit log for\n  in-flight inspection.\n- **`INC_APPEND_HISTORY` must be on in every interactive zsh.** A shell\n  started before you added the setopt still operates under the old options\n  and may overwrite the file on exit. Restart all zsh windows after\n  editing `.zshrc`.\n- **`fc -W` from any plugin/precmd overrides all setopts.** It does a full\n  file rewrite. None of the zsh history setopts gate it. If you discover\n  flushed entries vanishing, check your zsh plugins/themes for explicit\n  `fc -W` calls.\n- **Hard crash = no flush.** If Claude Code is killed (SIGKILL, OS reboot,\n  power loss), `SessionEnd` doesn't fire. Recover with\n  `agent-history flush -s \u003cid\u003e` against the still-complete audit log.\n- **PostToolUse on Bash only.** Other tool calls are ignored. Long-running\n  or aborted Bash calls that never complete are not captured.\n- **Claude Code only for now.** The `agent` field in log records is\n  hardcoded `claude-code`. Adapters for other agents would slot into the\n  hook payload parser in `hook.go`.\n\n## Layout\n\n```\n.claude-plugin/plugin.json   plugin manifest\n.claude-plugin/marketplace.json   self-referential single-repo marketplace\nhooks/hooks.json             SessionStart + PostToolUse + SessionEnd hooks\nscripts/bootstrap.sh         build the Go binary if stale\nscripts/run.sh               PostToolUse → agent-history run\nscripts/flush.sh             SessionEnd  → agent-history flush\nmain.go                      subcommand dispatch\nhook.go                      `run` handler: capture to JSONL audit log\nflush.go                     `flush` handler: batch-append captured commands\n                             to shell history at SessionEnd\nhistory.go                   shell-format helpers + batched append\nconfig.go                    XDG config load + first-run bootstrap\npaths.go                     XDG_CONFIG_HOME / XDG_DATA_HOME resolution\ntail.go                      `tail` subcommand\n*_test.go                    table tests\n```\n\n## Status\n\nv0.0.1. No promises of compatibility.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floresuso%2Fagent-history","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Floresuso%2Fagent-history","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floresuso%2Fagent-history/lists"}