{"id":51121489,"url":"https://github.com/im-anishraj/nactograph","last_synced_at":"2026-06-25T03:00:55.075Z","repository":{"id":358359170,"uuid":"1241085272","full_name":"im-anishraj/nactograph","owner":"im-anishraj","description":"Local-first flight recorder for AI coding agents: terminal replay, git diffs, redaction, risk findings, and shareable reports.","archived":false,"fork":false,"pushed_at":"2026-05-17T09:39:02.000Z","size":452,"stargazers_count":1,"open_issues_count":121,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-23T21:31:08.403Z","etag":null,"topics":["agentic-ai","ai","ai-agents","cli","code-review","codex","coding-agents","developer-tools","devtools","git","llm","local-first","nodejs","observability","redaction","risk-analysis","security","session-replay","terminal","typescript"],"latest_commit_sha":null,"homepage":"https://nactograph.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/im-anishraj.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":"ROADMAP.md","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-17T00:04:18.000Z","updated_at":"2026-05-17T11:00:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/im-anishraj/nactograph","commit_stats":null,"previous_names":["im-anishraj/noctograph","im-anishraj/nactograph"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/im-anishraj/nactograph","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/im-anishraj%2Fnactograph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/im-anishraj%2Fnactograph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/im-anishraj%2Fnactograph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/im-anishraj%2Fnactograph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/im-anishraj","download_url":"https://codeload.github.com/im-anishraj/nactograph/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/im-anishraj%2Fnactograph/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34757355,"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-25T02:00:05.521Z","response_time":101,"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":["agentic-ai","ai","ai-agents","cli","code-review","codex","coding-agents","developer-tools","devtools","git","llm","local-first","nodejs","observability","redaction","risk-analysis","security","session-replay","terminal","typescript"],"created_at":"2026-06-25T03:00:54.203Z","updated_at":"2026-06-25T03:00:55.069Z","avatar_url":"https://github.com/im-anishraj.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Nactograph\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eEvery AI agent run, replayed like evidence.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  A local-first flight recorder for AI coding agents. Nactograph captures terminal output, git diffs, tests, redaction decisions, dependency changes, and risk findings into shareable reports.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://nactograph.vercel.app\"\u003e\u003cstrong\u003eWebsite\u003c/strong\u003e\u003c/a\u003e\n  ·\n  \u003ca href=\"https://www.npmjs.com/package/nactograph\"\u003e\u003cstrong\u003enpm\u003c/strong\u003e\u003c/a\u003e\n  ·\n  \u003ca href=\"https://github.com/im-anishraj/noctograph/releases/tag/v0.1.0\"\u003e\u003cstrong\u003eRelease v0.1.0\u003c/strong\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/im-anishraj/noctograph/actions/workflows/ci.yml\"\u003e\u003cimg alt=\"CI\" src=\"https://github.com/im-anishraj/noctograph/actions/workflows/ci.yml/badge.svg\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/nactograph\"\u003e\u003cimg alt=\"npm version\" src=\"https://img.shields.io/npm/v/nactograph.svg?color=0b111a\" /\u003e\u003c/a\u003e\n  \u003cimg alt=\"Node 24+\" src=\"https://img.shields.io/badge/node-%3E%3D24-62e6ff\" /\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg alt=\"MIT License\" src=\"https://img.shields.io/badge/license-MIT-f7f4ea\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n```sh\nnactograph run -- codex \"fix failing auth tests\"\n```\n\nOutputs:\n\n```text\nblackbox-report.html\nblackbox.jsonl\nblackbox-pr-comment.md\n```\n\n![Nactograph report preview](docs/demo-report.png)\n\n## Why\n\nAI coding agents are fast, but review still needs evidence. What command ran? Which files changed? Did tests fail three times before passing? Did the agent touch `.env`, add a dependency, delete a test, or print a secret?\n\nNactograph turns an agent session into a local audit trail that a maintainer can inspect, attach to a pull request, or share without exposing raw secrets.\n\n## Highlights\n\n| Feature | What it gives you |\n|---|---|\n| PTY capture | The agent still runs normally while terminal output is recorded. |\n| Git snapshots | Before/after file contents, unified diffs, and changed-file metadata. |\n| JSONL event log | Append-only, machine-readable session history. |\n| Redaction engine | Secret files, tokens, private hosts, and custom patterns are masked before storage. |\n| Risk detector | Rule-based findings with severity and evidence. |\n| Static report | One self-contained HTML file; no server needed. |\n| PR summary | Markdown metrics and findings for code review. |\n\n## Install\n\n```sh\nnpm install -g nactograph\n```\n\nRequires Node 24 or newer.\n\n## Quick Start\n\n```sh\n# 1. Run any coding agent or shell command through Nactograph\nnactograph run -- codex \"fix failing auth tests\"\n\n# 2. Open the newest report\ncd blackbox-sessions\nopen */blackbox-report.html\n\n# 3. Use the generated review artifacts\ncat */blackbox-pr-comment.md\ncat */blackbox.jsonl\n```\n\nYou can wrap any command:\n\n```sh\nnactograph run -- npm test\nnactograph run -- pnpm exec vitest run\nnactograph run -- codex \"refactor the auth middleware\"\n```\n\n## What Gets Captured\n\n| Event | Payload |\n|---|---|\n| `SessionStart` | command, cwd, git head, output directory, redaction state |\n| `CommandRun` | command boundary and arguments |\n| `CommandOutput` | ANSI-stripped terminal stream with redaction applied |\n| `FileSnapshot` | before/after content, unified diff, hash, existence state |\n| `TestRun` | status, command, duration, output summary |\n| `DependencyChange` | added, removed, or changed packages |\n| `RiskyAction` | rule, severity, timestamp, evidence |\n| `SessionEnd` | exit code, signal, duration, artifact inventory |\n\n## How It Works\n\n```mermaid\nflowchart LR\n  A[\"nactograph run -- \u003cagent\u003e\"] --\u003e B[\"PTY wrapper\"]\n  B --\u003e C[\"Agent command\"]\n  B --\u003e D[\"Live JSONL event stream\"]\n  C --\u003e E[\"Git snapshot polling\"]\n  E --\u003e D\n  D --\u003e F[\"Redaction engine\"]\n  F --\u003e G[\"Risk detector\"]\n  G --\u003e H[\"blackbox-report.html\"]\n  G --\u003e I[\"blackbox-pr-comment.md\"]\n  F --\u003e J[\"blackbox.jsonl\"]\n```\n\nNactograph runs locally. It does not need a hosted recorder, database, or background service. Session artifacts are written to `./blackbox-sessions` by default.\n\n## Risk Rules\n\nNactograph is intentionally rule-based so maintainers can understand and improve every finding.\n\n| Rule | Severity | Detects |\n|---|---|---|\n| `secret_access` | high | secret-like file access or token-like output |\n| `lockfile_churn` | medium | repeated lockfile changes |\n| `dependency_added` | medium | newly added packages |\n| `dependency_removed` | medium | removed packages |\n| `test_deleted` | high | deleted `*.test.*` or `*.spec.*` files |\n| `test_failure_loop` | medium | repeated failed test runs |\n| `scope_creep` | medium | edits outside the expected working area |\n| `destructive_command` | high | `rm -rf`, force push, database drops, and similar commands |\n| `license_change` | medium | license file modifications |\n| `env_write` | high | writes to `.env` files |\n| `large_deletion` | medium | diffs with 100+ removed lines |\n\n## Reports\n\n| Artifact | Audience | Use it for |\n|---|---|---|\n| `blackbox-report.html` | humans | timeline replay, diffs, terminal output, filters, risk findings |\n| `blackbox.jsonl` | tools | audits, automation, future integrations |\n| `blackbox-pr-comment.md` | reviewers | pull request summary with metrics and findings |\n\n## CLI Reference\n\n```sh\nnactograph run [options] -- \u003ccommand...\u003e\n```\n\n| Flag | Default | Description |\n|---|---:|---|\n| `--output-dir \u003cdir\u003e` | `./blackbox-sessions` | Directory for session folders and report artifacts. |\n| `--redact` | on | Redact secrets before anything is stored. |\n| `--no-redact` | off | Disable redaction for private local debugging. |\n| `--redact-patterns \u003cpath\u003e` | none | Newline-delimited custom redaction patterns. Supports globs and `/regex/flags`. |\n\n## Redaction\n\nDefault redaction covers common secret files and values:\n\n- `.env`, `.env.*`, `*.pem`, `*.key`, `id_rsa`, `secrets.*`, `credentials.*`\n- `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `GITHUB_TOKEN`, `OPENAI_API_KEY`\n- long base64-like tokens\n- private IP ranges\n- localhost tokens in URLs\n\nRedaction audit entries include rule names and counts, never the raw value.\n\n## Monorepo\n\n```text\npackages/core     shared event schemas, redaction, risk detection\npackages/cli      nactograph CLI, PTY capture, git snapshots, report generation\npackages/viewer   embeddable React report viewer\npackages/site     Vercel landing page\n```\n\n## Development\n\n```sh\npnpm install\npnpm verify\n```\n\nUseful package commands:\n\n```sh\npnpm --filter nactograph dev -- run -- npm test\npnpm --filter @nactograph/site build\npnpm --filter nactograph-core test\n```\n\n## Release\n\nReleases are driven by GitHub Actions:\n\n- CI runs tests on pull requests.\n- npm publishing uses trusted publishing.\n- tagged releases attach binary builds for Linux, macOS, and Windows.\n\n## Contributing\n\nContributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md), follow Conventional Commits, and keep changes focused.\n\nGood first areas:\n\n- more risk rules\n- richer event cards\n- additional redaction patterns\n- integrations for PR comments\n- better examples from real agent sessions\n\n## Launch Copy\n\n\u003e I let an AI agent fix a bug. Nactograph replayed every command, every file edit, and the exact moment it broke the tests.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fim-anishraj%2Fnactograph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fim-anishraj%2Fnactograph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fim-anishraj%2Fnactograph/lists"}