[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-1704":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":13,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":14,"stars7d":13,"stars30d":15,"stars90d":14,"forks30d":14,"starsTrendScore":14,"compositeScore":16,"rankGlobal":9,"rankLanguage":9,"license":17,"archived":18,"fork":18,"defaultBranch":19,"hasWiki":20,"hasPages":18,"topics":21,"createdAt":9,"pushedAt":9,"updatedAt":22,"readmeContent":23,"aiSummary":24,"trendingCount":14,"starSnapshotCount":14,"syncStatus":25,"lastSyncTime":26,"discoverSource":27},1704,"ascent-research","actionbook\u002Fascent-research","actionbook","research cli for agent",null,"Rust",183,11,1,0,8,44.54,"Apache License 2.0",false,"main",true,[],"2026-06-12 04:00:11","# ascent-research\n\n[![Crates.io](https:\u002F\u002Fimg.shields.io\u002Fcrates\u002Fv\u002Fascent-research.svg)](https:\u002F\u002Fcrates.io\u002Fcrates\u002Fascent-research)\n[![GitHub Release](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fv\u002Frelease\u002Factionbook\u002Fascent-research)](https:\u002F\u002Fgithub.com\u002Factionbook\u002Fascent-research\u002Freleases)\n\n> **Your agent's next step up. Every session picks up where you left off. Every turn goes higher.**\n\n**One-line pitch.** `ascent-research` is an incremental research workflow CLI for AI agents: point it at a topic \u002F source tree \u002F Obsidian vault, and it will *keep* researching across sessions — fetching, citing, diagramming, and accreting a durable wiki you can come back to tomorrow and pick up exactly where you stopped.\n\n```bash\nascent-research new \"tokio internals 2026\" --slug tokio --preset tech\nascent-research add-local ~\u002Ftokio\u002Ftokio\u002Fsrc\u002Fruntime --glob '**\u002F*.rs'\nascent-research loop tokio --provider claude --iterations 12\nascent-research finish tokio --open           # coverage -> HTML -> audit\n# (next day)\nascent-research resume tokio && ascent-research loop tokio --iterations 8\n```\n\nBookmark-ready: every session lives as plain files under\n`~\u002F.actionbook\u002Fascent-research\u002F\u003Cslug>\u002F`, so Obsidian, VS Code, `grep`\nand `git` all work.\n\n## Author's positioning — an external handle for agent self-evolution\n\nA Claude Code or Codex conversation ends. The agent forgets everything.\nNext week you ask the same question — same search, same fetches, same\nhalf-formed understanding.\n\nI built `ascent-research` because I want my AI agents to **get smarter\nover time, not reset every session**. The on-disk session (`session.md`,\n`session.jsonl`, `wiki\u002F`, `SCHEMA.md`) is the agent's external long-term\nmemory — survives process death, carries across tool switches, inspectable\nand editable by the human. Every `loop` run isn't \"research this topic\nfrom scratch\"; it's \"continue the research we were doing, check what's\nunused from last time, append to the pages you've already written.\"\n\nThe agent-facing surface (actions like `write_wiki_page`,\n`append_wiki_page`, `digest_source`) exists specifically so the agent can\n*accrete* rather than *overwrite*. The infra-enforced rules\n(smell test, preserve_diagram_refs, figure-rich contract) exist so this\nlong-term memory stays clean without human QA every turn.\n\nWhether you use it standalone or as a skill inside a coding-agent\ninstance, the pitch is the same: **stop throwing away your agent's\nresearch work at the end of every conversation.** Keep it on disk. Let\nthe next turn stand on the last one's shoulders.\n\n## Two ways to use it\n\n`ascent-research` is a CLI that calls an LLM provider (Claude via\n`cc-sdk`, Codex via `codex app-server`, or `fake` for tests). Which\nprocess hosts the agent decides the usage shape:\n\n### Standalone — ascent-research runs its own loop\n\nRun the CLI directly; it spawns the provider itself and drives the\nresearch loop end-to-end, no outer agent needed. Good for\nbatch \u002F CI \u002F \"I just want a report.\"\n\n```bash\nascent-research new \"tokio internals\" --slug tokio\nascent-research add-local ~\u002Ftokio\u002Ftokio\u002Fsrc\nascent-research loop tokio --provider claude --iterations 12\nascent-research finish tokio --open\n```\n\n### Skill — driven from a Claude Code or Codex instance\n\nDrop the bundled skill into your Claude Code \u002F Codex config and the\nouter agent invokes the CLI per-turn as a tool. Good for interactive\nsessions where you want to mix research with coding \u002F writing work\nin the same conversation, or want the outer agent to plan the\nworkflow (decide what to ingest, when to query, when to synthesize).\n\n```bash\nln -s \"$PWD\u002Fskills\u002Fascent-research\" ~\u002F.claude\u002Fskills\u002Fascent-research\n# Then in a Claude Code session: \u002Fskill:ascent-research\n# Or just describe the task — \"research tokio's scheduler via source\" —\n# the skill triggers automatically.\n```\n\nBoth modes share the same on-disk session format, so you can start\na session in standalone mode and later resume it from inside a\nClaude Code \u002F Codex instance, or vice versa.\n\n---\n\n## What's new in 0.4.2\n\n- **Third LLM provider: OpenCode Go** ($10\u002Fmo subscription, OpenAI-\n  and Anthropic-compatible HTTP endpoints to DeepSeek \u002F Kimi \u002F GLM \u002F\n  Qwen \u002F MiniMax). Build with `--features provider-opencode-go`, set\n  `OPENCODE_API_KEY` + `ASR_OPENCODE_MODEL`, then\n  `ascent-research loop \u003Cslug> --provider opencode-go`.\n- Useful when Claude Code Pro \u002F ChatGPT Plus subscriptions are out of\n  reach (cost or payment-region constraints). All knobs are env-driven\n  (`ASR_OPENCODE_PROTOCOL`, `ASR_OPENCODE_TEMPERATURE`,\n  `ASR_OPENCODE_MAX_TOKENS`, `ASR_OPENCODE_TIMEOUT_MS`).\n- Also works as `ASR_BILINGUAL_PROVIDER=opencode-go` for\n  `synthesize --bilingual` Chinese translation.\n- **CLI defaults unchanged** — `--provider` still defaults to `fake`;\n  opt in to `opencode-go` explicitly.\n- Thanks to [@Paul-Yuchao-Dong](https:\u002F\u002Fgithub.com\u002FPaul-Yuchao-Dong)\n  for raising the use case and contributing the initial design (PR #19).\n\nSee `CHANGELOG.md` for the full design rationale incl. what was\ndeliberately not adopted from the PR.\n\n---\n\n## What's new in 0.4.1\n\n- **x.com \u002F twitter.com tweet capture works end-to-end** through the V2\n  browser backend. v0.4.0's generic runcode JS returned ~160 bytes of\n  X's left-nav chrome only; 0.4.1 adds an `XTweet` runcode flavor that\n  waits for `article[data-testid=\"tweet\"]` (not `networkidle`), scrolls\n  with **snapshot-collect across virtualized DOM** so the main tweet\n  isn't unmounted out of the result, and reads up to 25 thread articles\n  with image \u002F video poster URLs inlined as markdown `![](url)`.\n- **3 new tech preset rules**: `x-tweet-status`, `x-profile`,\n  `x-search-live` — explicit kinds for `route` debugging.\n- **Bugfix in `md_parser::extract_http_links`**: markdown image syntax\n  `![alt](url)` is now correctly excluded from the cited-sources scan,\n  so embedding pictures of cited tweets no longer trips\n  `sources_hallucinated`.\n\nLive impact (same URLs, before vs after):\n\n| URL | 0.4.0 | 0.4.1 |\n|---|---|---|\n| `x.com\u002F\u003Cuser>\u002Fstatus\u002F\u003Cid>` (any) | 162 B chrome | **2-3 KB** main tweet + thread + media |\n\nSee `CHANGELOG.md` for full notes and `specs\u002Fx-com-tweet-runcode-flavor.spec.md`\nfor the design (33 BDD scenarios, lint 100%).\n\n---\n\n## What's new in 0.4.0\n\n- **V2 Actionbook MCP backend is now the default** for browser-rendered\n  fetches (Cloud Worker at `edge.actionbook.dev\u002Fmcp` + Chrome extension\n  over WSS). Set `ACTIONBOOK_BACKEND=v1-cli` to keep the old local-CLI\n  path — it's a **permanent fallback**, not slated for removal.\n- **Catalog seed pre-fetch**: every `add` \u002F `batch` first probes the V2\n  catalog and seeds matching actions into the session wiki, so the\n  agent knows what's known about a site before navigating.\n- **Composite source fetch**: one rule can fan out into N parts\n  (e.g. postagent metadata + browser rendered) merged under\n  `composite-v1`; short-circuits on first part failure with a labelled\n  `composite_failed_part` event.\n- **3 new autoresearch actions** for the loop: `actionbook_search`,\n  `actionbook_manual`, `actionbook_run_code`.\n- **New flags** on `add` \u002F `batch`: `--frame-id`, `--run-code-args`,\n  `--reseed`, `--actionbook-backend`.\n- **Default per-source timeout** raised from 30 s → 90 s (V2 server's\n  inner run-code budget is 60 s; extra 30 s covers edge overhead).\n- Fixes: smell `www.` ↔ apex equivalence; CJK \u002F UTF-8 docs now pass the\n  `add-local` text detector; user `--timeout > 60s` is no longer\n  silently truncated by the V2 server's hard cap.\n\nSee `CHANGELOG.md` for the full list and `docs\u002Frfc\u002Fv2-session-export-to-postagent.md`\nfor the cross-tool RFC that didn't ship in this release.\n\n---\n\n## Why it's different\n\nFive properties — each validated end-to-end across four live research\nsessions (tokio internals, an Obsidian agent-SE series, a mixed\nonline-plus-local AI coding agents comparison, and self-research on\nthis repo):\n\n### 0. Autoresearch lineage — 2-file resume, extended to reports\n\nInherits the core loop architecture from\n[karpathy\u002Fautoresearch](https:\u002F\u002Fgithub.com\u002Fkarpathy\u002Fautoresearch)\nand [pi-autoresearch](https:\u002F\u002Fgithub.com\u002Fdavebcn87\u002Fpi-autoresearch):\na fresh agent can resume any session from two files —\n`session.md` (human-readable living doc) + `session.jsonl`\n(append-only event log) — even after process death, context reset,\nor a week of inactivity. Where the original autoresearch optimizes a\nsingle scalar (training loss, bundle size, test speed) via\n`edit → benchmark → keep-or-revert`, `ascent-research` generalizes\nthe same loop grammar to *research*:\n`plan → fetch → digest → write_section \u002F write_wiki_page \u002F write_diagram`\nproducing a figure-rich report plus a durable cross-session wiki\ninstead of a single optimized number.\n\n### 1. Incremental research — sessions resume, knowledge accretes\n\n`ascent-research resume \u003Cslug>` picks up exactly where a prior turn\nstopped. Wiki pages *accrue* via `append_wiki_page` — new findings\ngrow existing entity pages instead of overwriting them. Coverage\nsignals (`sources_unused`, `diagrams_referenced`, `wiki_pages`,\n`wiki_total_bytes`) let each loop run know *what's still open* from\nthe previous turn, so it continues rather than restarts. One-shot\nDR tools can't do this — when they finish, they're done.\n\n### 2. Three-way ingest, one pipeline\n\n`add` (HTTP via `postagent`) + `add-local` (file trees) + browser\nfallback (via `actionbook browser` for JS-heavy pages) all flow\nthrough the same smell-test → event-log → wiki → report path. A\nsingle session can cite GitHub READMEs, arXiv papers, blog posts,\nand your private Obsidian notes side-by-side in one wiki page's\nsources list — the renderer doesn't care about URL scheme.\n\n### 3. Figure-rich by contract\n\nNarrative-only output is considered incomplete. The loop's system\nprompt carries a non-negotiable FIGURE-RICH CONTRACT: target ≥ 1\nhand-drawn SVG per numbered section, bidirectional rule that every\n`![](diagrams\u002Fx.svg)` markdown reference must have a matching\n`write_diagram` action and vice versa, infra-level guarantee that\nsection overwrites never drop figures. Every SVG is inline\n(no external assets, no screenshots) and the HTML report has a\nclickable wiki TOC + EN\u002FZH bilingual toggle.\n\n### 4. Infra-enforced correctness + machine-readable errors\n\nAgents can't \"just summarize this for me.\" Every fetch runs through\na smell test at the CLI layer before the LLM sees it; rejections\nbecome typed events. Overwrites preserve figures. Wiki writes are\nappend-safe. Coverage computes `sources_hallucinated` (URLs cited\nbut never fetched) as a `report_ready` blocker. Every error returns\na machine-readable code (`NO_ACTIVE_SESSION`, `SMELL_REJECTED`,\n`DIAGRAM_OUT_OF_BOUNDS`, `WIKI_EMPTY`, …) so agents route recovery\ndeterministically without parsing prose.\n\n---\n\n## Install\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Factionbook\u002Fascent-research\ncd ascent-research\n\n# Full build (loop + Claude provider) — what live sessions need\ncargo build -p ascent-research --release --features \"autoresearch provider-claude provider-codex\"\n\nexport PATH=\"$PWD\u002Ftarget\u002Frelease:$PATH\"\nascent-research --help\n```\n\nAlternative feature sets:\n\n```bash\n# Minimal — no autonomous loop, no LLM\ncargo build -p ascent-research --release\n\n# Loop with fake provider only (for scripted tests)\ncargo build -p ascent-research --release --features autoresearch\n\n# Loop with Codex instead of Claude\ncargo build -p ascent-research --release --features \"autoresearch provider-codex\"\n```\n\nPrereqs for online ingest: Rust stable (edition 2024),\n[`postagent`](https:\u002F\u002Fgithub.com\u002Factionbook\u002Fpostagent) for HTTP API fetches,\nand (for JS-heavy pages) the Actionbook Chrome extension — see below.\nNeither is required if you only use `add-local`.\n\n### Browser ingest backends\n\n`ascent-research` picks between two actionbook backends based on\n`ACTIONBOOK_BACKEND` (default `v2-mcp`):\n\n| Env value | Path | What's needed |\n|---|---|---|\n| `v2-mcp` (default) | Cloud MCP at `edge.actionbook.dev\u002Fmcp` + Actionbook Chrome extension over WSS | `ACTIONBOOK_API_KEY` (an `ak_*` token), Chrome extension installed & signed in |\n| `v1-cli` | Local `actionbook` CLI subprocess (offline-capable fallback, permanently supported) | The [`actionbook`](https:\u002F\u002Fgithub.com\u002Factionbook\u002Factionbook) binary on `PATH`, and your Chrome profile reachable by it |\n\n**V2 setup**:\n\n1. Install the **Actionbook Cloud (v2)** Chrome extension (v0.2.0-alpha.4\n   or later). Unpacked-load it from `chrome:\u002F\u002Fextensions` → Load unpacked.\n2. Sign in via the extension popup.\n3. Get an `ak_*` token from [actionbook.dev\u002Fdashboard\u002Fapi-keys](https:\u002F\u002Factionbook.dev\u002Fdashboard\u002Fapi-keys) and export it:\n   ```bash\n   export ACTIONBOOK_API_KEY=ak_xxxxxxxxxxxxxxxx\n   ```\n   ⚠️ **Do not commit this token to git.** Prefer `.envrc` + direnv or a\n   secret manager. `ascent-research` never echoes the token in error\n   messages or logs.\n\n**Recommended: dedicated Chrome profile.** V2 drives the page through\n`chrome.debugger`, which Chromium will refuse to attach when other\nextensions inject `chrome-extension:\u002F\u002F` content frames into the target\npage (most password managers, AI sidebars, translation extensions, and\nDevTools extensions do this). Symptom: every browser fetch fails with\n`DEBUGGER_ATTACH_CONFLICT`.\n\nThe cleanest fix is a dedicated Chrome profile that only has the\nActionbook extension installed:\n\n```bash\n# macOS — launch a specific profile directly:\nopen -na \"Google Chrome\" --args --profile-directory=\"Profile 2\"\n```\n\n(Replace `Profile 2` with the directory name shown at `chrome:\u002F\u002Fversion`\nin your dedicated profile.)\n\n**Other V2 env vars**:\n\n| Env | Default | Purpose |\n|---|---|---|\n| `ACTIONBOOK_BACKEND` | `v2-mcp` | `v1-cli` to revert to subprocess; unknown values are fatal |\n| `ACTIONBOOK_MCP_ENDPOINT` | `https:\u002F\u002Fedge.actionbook.dev\u002Fmcp` | Point at staging or a local worker |\n| `ACTIONBOOK_API_KEY` | — | `ak_*` token (required for v2-mcp) |\n| `ACTIONBOOK_BIN` | `actionbook` | V1 path only; ignored under v2-mcp |\n| `ACTIONBOOK_BROWSER_SESSION` | — | V1: shared session name. V2: tab-handle prefix (lets multiple ascent instances share one Chrome without colliding) |\n| `ACTIONBOOK_STDOUT_CAP` | 16 MB | Cap on per-call response body (both backends) |\n\n---\n\n## Three shapes of research\n\n### A. Survey a topic from public sources\n\n```bash\nascent-research new \"state-space models 2026\" --slug ssm --preset tech\nascent-research batch \\\n  https:\u002F\u002Farxiv.org\u002Fabs\u002F2111.00396 \\\n  https:\u002F\u002Farxiv.org\u002Fabs\u002F2312.00752 \\\n  https:\u002F\u002Fgithub.com\u002FHazyResearch\u002Fstate-spaces \\\n  --concurrency 4\nascent-research loop ssm --provider claude --iterations 10\nascent-research finish ssm --bilingual --open\n```\n\nPDF export is opt-in. The default backend is local and free: it uses an\nisolated headless Chromium when available, so the HTML stays on your machine\nand no paid API is required:\n\n```bash\nascent-research synthesize ssm --bilingual --pdf\n```\n\nThe local backend discovers Playwright Chromium first. If it is not installed,\nrun `npx playwright install chromium` or set `ASR_PDF_CHROME_BIN` to a known\nsafe browser binary. Desktop Google Chrome is not auto-launched by default; set\n`ASR_PDF_ALLOW_SYSTEM_CHROME=1` only if you explicitly want that fallback.\n\n### B. Deep-dive a library's source tree\n\n```bash\nascent-research new \"axum internals\" --slug axum --preset tech\nascent-research schema edit        # set your \"what to emphasize\"\nascent-research add-local ~\u002Faxum\u002Faxum\u002Fsrc --glob '**\u002F*.rs'\nascent-research loop axum --provider claude --iterations 12\nascent-research finish axum --open\n```\n\n### C. Structure your Obsidian vault\n\n```bash\nascent-research new \"my agent-SE notes\" --slug notes --preset tech\nascent-research add-local ~\u002Fvault\u002Fagent-notes --glob '**\u002F*.md'\nascent-research loop notes --provider claude --iterations 10\nascent-research wiki query \"what's my stance on code review for AI?\" \\\n  --save-as my-code-review-stance\n```\n\n### D. Audit GitHub star-trust signals\n\n`github-audit` creates a deterministic evidence artifact first; the LLM only\ninterprets that artifact and any follow-up public context. It reports a\nhuman-facing trust score, machine-facing risk score\u002Fband, confidence, reasons,\nand evidence, not a hard “fake\u002Freal” verdict.\n\n```bash\nascent-research github-audit dagster-io\u002Fdagster \\\n  --depth timeline --sample 500 --out audit.json --html audit.html\nascent-research new \"dagster-io\u002Fdagster GitHub trust audit\" \\\n  --slug dagster-trust --preset github-trust --tag fact-check\nascent-research add-local audit.json --slug dagster-trust\nascent-research loop dagster-trust --provider claude --iterations 8\nascent-research finish dagster-trust --open\n```\n\nUse `audit.html` when the user needs the trust decision surface directly:\ntrust score, risk score, confidence, metric dashboard, reasons, and evidence\ngaps. Use the research session only for contextual follow-up around that\ndeterministic score.\n\nFull command reference, error-code triage, loop contracts, and scenario\nplaybooks: see [`skills\u002Fascent-research\u002FSKILL.md`](skills\u002Fascent-research\u002FSKILL.md).\n\n---\n\n## Session layout\n\nEach project is one directory under `~\u002F.actionbook\u002Fascent-research\u002F\u003Cslug>\u002F`.\nEverything is plain files — markdown, JSON lines, SVG, TOML — so your\neditor \u002F grep \u002F git \u002F Obsidian all work without a custom client.\n\n| File | Purpose |\n|------|---------|\n| `session.md` | Narrative — numbered sections, overview, aside. Report spine. |\n| `session.jsonl` | Append-only event log. Sources, attempts, loop steps. Authoritative. |\n| `SCHEMA.md` | User-editable session guidance. Loop re-reads each turn. |\n| `wiki\u002F*.md` | Persistent entity \u002F concept \u002F analysis pages with cross-links. |\n| `diagrams\u002F*.svg` | Hand-drawn figures inlined into the HTML report. |\n| `raw\u002F` | Raw fetched content, one file per accepted source. |\n| `report.html` | Rendered editorial output — wiki TOC, inline SVGs, optional bilingual toggle. |\n| `report.pdf` | Optional local PDF export of `report.html`, created only by `synthesize --pdf` or `--pdf-output`. Defaults to isolated local Chromium. |\n\nOverride the root via `ACTIONBOOK_RESEARCH_HOME=\u002Fsome\u002Fpath`. Legacy\n`~\u002F.actionbook\u002Fresearch\u002F` is read as a fallback so sessions from\nv0.2 keep working.\n\n---\n\n## Agent integration\n\n`skills\u002Fascent-research\u002FSKILL.md` is a bundled Claude Code \u002F Codex skill\ndescribing the full workflow with nine scenario playbooks, error-code\ntriage, and build-target matrix. Expose it on your global skill path:\n\n```bash\nln -s \"$PWD\u002Fskills\u002Fascent-research\" ~\u002F.claude\u002Fskills\u002Fascent-research\n```\n\n---\n\n## Development\n\n```bash\ncargo test -p ascent-research                         # core suite\ncargo test -p ascent-research --features autoresearch # + loop suite (fake provider)\n```\n\nAll integration tests use a `FakeProvider` replaying scripted JSON\nturns, so the full suite never hits a real LLM and needs no network.\n\n---\n\n## Project lineage\n\n- Core 2-file resume loop inherited from\n  [karpathy\u002Fautoresearch](https:\u002F\u002Fgithub.com\u002Fkarpathy\u002Fautoresearch)\n- Per-session wiki layer inspired by karpathy's\n  [LLM Wiki gist](https:\u002F\u002Fgist.github.com\u002Fkarpathy\u002F442a6bf555914893e9891c11519de94f)\n- Widget \u002F dashboard pattern borrowed from\n  [pi-autoresearch](https:\u002F\u002Fgithub.com\u002Fdavebcn87\u002Fpi-autoresearch)\n- Previously named `research-rs` (v0.1 \u002F v0.2); renamed to\n  `ascent-research` in v0.3 to foreground the incremental-research story\n\n---\n\n## License\n\nApache-2.0.\n","ascent-research 是一个为AI代理设计的增量研究工作流命令行工具。它能够持续地对指定主题或源代码树进行研究，跨会话保持研究进度，并生成可持久化的wiki文档，支持引用、图表绘制等功能。项目使用Rust语言开发，具备良好的性能和稳定性。适合需要长期跟踪某一技术领域进展、构建知识库或进行深度研究的场景，如软件开发中的技术调研、学术研究等。此外，其生成的所有会话内容均以纯文本文件形式保存于本地，便于与Obsidian、VS Code等工具集成使用。",2,"2026-06-11 02:45:34","CREATED_QUERY"]