Aiscribe · Local-first AI Session Report Aggregator

Local-first, privacy-first. Collects your AI coding/chat tool sessions from your own machine, groups them by project, and turns them into daily/weekly reports (Markdown / Word) — exposed to any AI client as an MCP server.

The MCP tools fetch every real message you sent today; your AI assistant reads them and writes the report. That division of labour is why the output is far better than template-only reporting.

English | 简体中文

---

Why

Your day is scattered across several AI tools: code edits in an IDE, debugging in a chat window, design notes in another tool. When report time comes you reconstruct it from memory — mixed-up projects, wrong dates, vague summaries.

Aiscribe does it differently:

1. Read locally — pull what you actually sent today from each tool's local database/logs, filtered by a single timezone (Asia/Shanghai). Nothing leaves your machine.
2. Let the AI summarise — hand the raw conversations to your AI assistant over MCP; it merges duplicates, distils topics (not messages), and groups them by project.
3. Format and save — emit a fixed 1、Project / ①、Topic layout with a detailed version + a short version, written to local reports/ as md, docx, or a self-contained shareable html page.

Features

• 16 built-in native connectors — CodeBuddy CN, TRAE, Codex, dsh, Claude Code, Gemini CLI, Qwen Code, iFlow, Copilot Chat, Cline, Roo Code, Kilo Code, Cursor, Doubao, WorkBuddy, Kimi; each reads the tool's own local files, no Cass or other indexer required
• Understands, doesn't template — get_conversations returns per-project raw user inputs; the client AI writes the report
• Correct date filtering — only sessions starting that day, or spanning the night (≤ 1 day); a week-old session touched once won't leak into today
• Automatic project grouping — keyword rules (projects.json) → title hints → cwd's last path segment fallback; new projects need zero config
• Daily / weekly / custom range, rendered in Asia/Shanghai time
• Markdown, Word, or shareable HTML — --format docx writes hand-rolled WordprocessingML, --format html writes a single self-contained page (inline CSS, no JS, no external assets); both pure stdlib
• Optional LLM polish (--llm, DeepSeek-compatible): the model may only rewrite each item's text — the report skeleton (report title, project sections, item order) is machine-built and every reply must pass a structure/format check, otherwise it falls back to the template silently
• Zero third-party dependencies (core) — data access, report building, and MCP run on the Python standard library alone, no pip install needed. The one exception is the guide page frontend: ui.py's server is still stdlib, but the page pulls Tailwind / React / Framer Motion from a public CDN, so the first load needs internet. Offline it shows an explicit notice instead of a blank page and points you at the CLI or MCP. Session data stays local while it is read, filtered and laid out; only when you opt into AI polish or ask a cloud model to read full sessions does that text enter the model context.
• Any MCP client — stdio transport; TRAE, Claude Code, Cursor, dsh all work
• One-step DSH install — install dsh-aireport from the DSH plugin market; the package bundles a Windows sidecar, so no Python install is required (source and standalone MCP setups still work)
• Local guide page — python -m ai_report ui serves a loopback-only six-screen wizard: splash → ① per-source real scan → ② date / week / custom range → ③ pick sessions by project (with time trimming) → ④ template and output format → generating screen → generate the report on the spot (template-only, written straight into reports/) or copy a ready-to-paste instruction for your AI
• Time trimming — set a start/end per session in the guide page; segments outside the window are dropped by the tool itself (not by a prompt hint), so they can never leak into the report
• Format cloning — upload the reports you already write (md / txt / docx / image), the layout is extracted locally into a template, and every later report reproduces your format (structure only, never the sample's content)

Quick start

# 0) Python 3.9+, no pip install needed
git clone https://github.com/5yeah/Aiscribe.git
cd Aiscribe

# 1) See which data sources were auto-discovered on this machine
python -m ai_report sources
python -m ai_report config

# 2) Template-only report first (no AI needed)
python -m ai_report daily --date 2026-10-16

# 3) Recommended: open the local guide page (scan → pick → generate, or copy an instruction)
python -m ai_report ui

# 4) Or wire the MCP server + Skill into your AI client

DSH plugin (no Python required)

Search for Aiscribe (dsh-aireport) in the DSH 0.2.x plugin market and install it, then start a new session. Or use the CLI:

dsh plugin --profile web add dsh-aireport

0.1.0 bundles a Windows x64 runtime only; macOS/Linux builds will ship as separate platform packages. Reports and config live in ~/.aireport/. See dsh-plugin/README.md.

Local guide page

python -m ai_report ui            # port 5071, opens your browser
python -m ai_report ui --port 5080 --no-open

Bound to 127.0.0.1 only. Four steps: source scan (lists only the tools really detected on this machine — each lights up after it is really read, tagged with its content level; once scanning finishes the list is sorted by session count, and tools that are not installed are folded into a collapsed “N tools not detected” row), time window (daily / the natural week of a chosen day / an explicit custom range), session picking (lanes per project, all selected by default — anything you untick never reaches the AI; each session can also be cut to a time window with ✂), template & output (md / docx / html, plus format cloning from your old reports).

The generating screen offers two ways out, pick either:

• Generate report (local template by default) — render and write the report into reports/ locally, filtered by your ticks and trims. Only if you manually tick “AI polish” and have an engine configured does the draft text (daily summaries plus, when available, up to 120 chars of the AI reply — not the full transcript) go to the model. The page states plainly whether the body was summarised or is still the raw template draft. With no engine configured it does not pretend to summarise — it falls back and says why.
• Copy instruction — paste the generated instruction (carrying the record ids you selected and the format spec) into your AI chat; the AI reads the raw sessions and summarises, which gives the best quality. In that path the file is written by your AI client via save_report.

Browsing every past session

The wizard only shows the material for the day you picked. To browse all history, hit “浏览历史会话” in the top-right corner, or open http://127.0.0.1:5071/browse directly:

• filter by source (with real per-source counts) and by project; pick any date range
• the search box covers titles, summaries and per-message text (/ to focus, Esc to close)
• click a row for a right-hand drawer with the full per-message body, timestamps and project path; sources that only keep titles (WorkBuddy, Doubao…) are labelled “no body” instead of looking empty
• deep links work: /browse?id=dsh|session-xxxx
• listing is cached for 30 s so paging/searching never re-scans the disk; Refresh forces a re-read

Summarisation engine (optional)

Summarisation only happens on the already-collapsed draft level: the draft is locally assembled (e.g. CodeBuddy CN's real input timeline for the day, each entry capped at 400 chars) and may append up to 120 chars of the assistant's conclusion when one exists. It is not the full transcript, but it does contain fragments of your own input — decide accordingly before enabling it. Configure it via a gitignored llm.json or the matching environment variables:

{ "provider": "deepseek", "model": "deepseek-chat", "api_key": "sk-..." }

• DeepSeek — set DEEPSEEK_API_KEY, or put it in llm.json
• Nothing leaves the machine — switch "provider" to "ollama" and point "model" at a model you have pulled locally (e.g. qwen3.8:27b); talks to http://127.0.0.1:11434, no key needed
• The CLI has the same switch: python -m ai_report daily --llm (falls back to the template on failure)

Time trimming (cut a session down to a time window)

A long session often mixes yesterday's leftovers with today's work. Open the guide page, click the ✂ button on a session chip, and set a start/end time. Everything outside that window is dropped inside the tool — get_conversations simply never returns it, so the AI cannot write it back in. The preview and the material handed to the AI stay in sync, and a 已剪辑 badge marks the chip (清空全部剪辑 undoes everything). Times are Beijing time; an end earlier than the start means an overnight window (e.g. 22:30 ~ 02:00); segments without a timestamp are always kept. Trims live in <data dir>/trims.json (the repo root when running from source, ~/.aireport when installed; override with AIREREPORT_TRIMS, gitignored).

Format cloning (reproduce the report layout you already use)

python -m ai_report learn old-daily.md --name my-format   # learn from one sample
python -m ai_report learn a.md b.docx --name my-format    # several samples vote on the common layout
python -m ai_report templates                             # list what has been learned
python -m ai_report daily --date 2026-10-16 --template my-format

• Structure only — title line, header line, project heading, item marker, TODO block, footer, dual version or not. The sample's actual work content is never carried over.
• Image samples — no OCR (keeps the zero-dependency rule). Images are archived and the host AI is asked to read them and write the structure back via the save_template MCP tool.
• Two consumers — the AI path (get_format_spec injects the spec into the prompt; primary) and the CLI path (--template styles the template-only output).
• Templates live in templates/*.json (override with AIREREPORT_TEMPLATES_DIR, gitignored); set AIREREPORT_TEMPLATE to choose which one is active by default.

MCP + Skill (recommended)

MCP config (point the args at your clone):

{
  "mcpServers": {
    "aireport": {
      "command": "python",
      "args": ["<repo>/run_mcp_stdio.py"]
    }
  }
}

Skill: copy skills/ai-report/SKILL.md into your client's skills directory (TRAE: .trae/skills/; Claude Code: ~/.claude/skills/).

Then just ask: "Generate my report for today." The AI runs list_sources → get_conversations (overview, then per-project detail) → summarise → save_report.

Client-by-client setup and known pitfalls (including TRAE's space-splitting command) live in mcp/README.md (Chinese).

How it works

flowchart LR
    subgraph L1["L1 Connectors (local files only, offline)"]
        A1[CodeBuddy CN / TRAE] --> U[UnifiedRecord]
        A2[Codex / dsh / Claude Code] --> U
        A3[Gemini CLI / Qwen Code / iFlow] --> U
        A4[Copilot Chat / Cline / Roo / Kilo / Cursor] --> U
        A5[Doubao / WorkBuddy / Kimi] --> U
    end
    U --> L2["L2 Index: merge / dedupe / classify / date filter"]
    L2 --> MCP["MCP: get_conversations returns raw chats"]
    MCP --> AI["Client AI reads & summarises"]
    AI --> SAVE["save_report → md / docx / html"]
    L2 --> TPL["generate_report (template-only fallback)"]
    TPL --> OUT["reports/"]
    SAVE --> OUT

Report format

One file, two versions — detailed on top, a --- separator, short version below.

# AI 日报 2026-10-16

**1、订单服务（重构下单链路，09:06–18:20）：**

①、接口契约梳理：确认 v2 字段清单并落成 contracts/order.md。

②、超时问题定位：定位到连接池配置过小，改为 20 后压测回归通过。

---

# AI 日报（简洁版）2026-10-16

**1、订单服务：**

①、接口契约梳理

②、超时问题定位

Rules (hard-coded in the Skill): projects use **1、Name：**, topics use ①②③; the short version drops the parenthetical context and keeps only the text before the ： of each detailed bullet.

CLI

python -m ai_report daily  [--date YYYY-MM-DD] [--llm] [--out FILE] [--format md|docx|html] [--template NAME]
python -m ai_report weekly [--date YYYY-MM-DD] [--template NAME]
python -m ai_report range  --start YYYY-MM-DD --end YYYY-MM-DD [--template NAME]
python -m ai_report sources
python -m ai_report config
python -m ai_report learn SAMPLE... [--name NAME]   # learn a layout from past reports
python -m ai_report templates                      # list learned format templates
python -m ai_report mcp --stdio          # MCP stdio (for AI clients)
python -m ai_report mcp --port 5070      # optional local HTTP, 127.0.0.1 only
python -m ai_report ui                   # local guide page, 5071, loopback only

Windows helpers: scripts/run_daily.bat / scripts/run_weekly.bat; scheduling example: automation_example.json.

Supported sources

All connectors are native: they read each tool's own local files, so no Cass-style indexer and no extra packages are needed. The only exception is zstd-compressed sessions (Codex, dsh): with zstandard installed or a zstd binary on PATH you get the full text; without either they degrade to metadata-only — never an error, never a crash.

Full per-message text (best report quality)

Source	Auto-discovered location	What is available locally
CodeBuddy CN	%APPDATA%/CodeBuddy CN/	Session metadata + raw sent inputs via onAgentStart: userInput= in logs (user side only)
TRAE	~/.trae-cn/memory/projects/	Per-message summaries + topics.md session summaries
Codex	~/.codex/	state_5.sqlite metadata + projected history / rollout-*.jsonl.zst user and assistant turns
dsh	~/.dsh/sessions/	Per-message user and assistant turns from the session.v4.jsonl.zstd event stream
Claude Code	~/.claude/projects/	**/*.jsonl user/assistant turns (sidechains and local-command noise skipped)
Gemini CLI	~/.gemini/tmp/*/chats/	session-*.json user/model messages
Qwen Code	~/.qwen/tmp/*/chats/	Same format (Gemini CLI fork)
iFlow	~/.iflow/tmp/*/chats/	Same format (Gemini CLI fork)
Copilot Chat	%APPDATA%/Code/User/workspaceStorage/*/chatSessions/	VS Code built-in chat *.jsonl: prompt + response parts
Cline	…/globalStorage/saoudrizwan.claude-dev/tasks/	api_conversation_history.json user/assistant messages
Roo Code	…/globalStorage/rooveterinaryinc.roo-cline/tasks/	Same format (same lineage)
Kilo Code	…/globalStorage/kilocode.kilo-code/tasks/	Same format (same lineage)
Cursor	%APPDATA%/Cursor/User/globalStorage/state.vscdb	cursorDiskKV composerData:* + typed bubbleId:*

Every message carries a role: user is what the person asked, assistant is what the AI concluded or changed. “What was done” in a report comes from the assistant side — never rewrite the question into a past-tense claim.

Titles / metadata only (bodies live in the cloud)

Source	Auto-discovered location	What is available locally
Doubao	%LOCALAPPDATA%/Doubao/User Data/Default/IndexedDB	Titles and timestamps (LevelDB / V8 blobs)
WorkBuddy	~/.workbuddy/workbuddy.db	Titles and timestamps (cwd is its own workspace dir)
Kimi	%APPDATA%/kimi-desktop/	Metadata + edited file paths (used to locate the project dir)

Every path is derived from %APPDATA% / %LOCALAPPDATA% / the user profile — no hard-coded usernames — and each can be overridden by an environment variable (see python -m ai_report config).

Configuration

Env var	Purpose	Default
AIREREPORT_HOME	Data directory (reports, templates, config, trims)	repo root from source; ~/.aireport when installed
AIREREPORT_REPORTS_DIR	Report output directory	<data dir>/reports
AIREREPORT_TEMPLATES_DIR	Learned format templates directory	<data dir>/templates
AIREREPORT_TEMPLATE	Default active format template	newest learned template
AIREREPORT_TRIMS	Session time-trim file	<data dir>/trims.json
AIREREPORT_PROJECTS	Project classification rules	<repo>/projects.json, then ~/.aireport/projects.json, then built-ins + cwd fallback
CODEBUDDY_CN_DB … VSCODE_GLOBAL_STORAGE	Override a source path (multi-dir values use ;)	Auto-discovered
AIREREPORT_SCAN_ALL_USERS	Set 1 to also read other Windows users' session dirs on this machine	Off — other people's sessions are not read by default
DEEPSEEK_API_KEY, LLM_PROVIDER	Optional LLM polish	--llm falls back to template mode

Copy projects.example.json to projects.json to pin your own project names.

Privacy

• Connectors read local files only and never go online; Aiscribe has no telemetry and does not upload sessions on its own
• Tool output enters the model context. When a cloud model drives the report through MCP, get_conversations(detail="full") is effectively sending those transcripts to that model provider. The server tells models to start with detail="summary" and to read only the projects/dates needed
• Only the current user's directories are read; other users on the same machine require AIREREPORT_SCAN_ALL_USERS=1
• Only the skeleton draft (summaries, plus up to 120 chars of assistant text when available) goes to a configured LLM endpoint, and only when you opt into AI polish (--llm / UI tick / polish=true). The full raw transcript is not sent by the summariser itself
• Reports stay in local reports/; both the optional HTTP mode and the guide page bind to 127.0.0.1 only
• The guide/browse pages validate Host and Origin and reject anything that is not a loopback, same-origin request — this blocks DNS rebinding (a domain pointed at 127.0.0.1 driving your local port)
• .gitignore excludes reports/, projects.json, trims.json, dingtalk_config.json, automation.json

Known limitations

• Every collection re-reads every source: 166 local records ≈ 0.7 s. The time sits in the pure-Python parsing of dsh, CodeBuddy CN and Doubao (a thread pool measured 1.01x — GIL-bound, so it is not used). The real fix is a file-fingerprint cache — not implemented yet.
• Assistant text is not available everywhere: CodeBuddy CN only reconstructs user inputs; WorkBuddy, Kimi and Doubao keep titles only. Those sources can only contribute “what was asked”.
• Codex / dsh need zstd: with zstandard or a zstd binary you get the text, otherwise the connector degrades to metadata.

Layout

ai_report/            core package (stdlib only)
  connectors/         L1: base / common / codebuddy_cn / trae / codex / dsh / claude_code /
                      gemini_cli / vscode_chat / cline / cursor / doubao / workbuddy / kimi / registry
  index.py            L2: merge, dedupe, classify, date filter, shared window/payload helpers
  generator.py        L3: daily/weekly/range templates (can follow a learned layout)
  template.py         format cloning: extract layout from past reports, store specs for the AI
  trim.py             session time trimming: window parsing, segment clipping, trims.json store
  html.py  docx.py    exports: self-contained shareable page / Word
  llm.py              L4: optional synthesis (rewrites item text only, must pass format check)
  cli.py  mcp_server.py
  ui.py  web/         local guide page: stdlib HTTP server + six-screen wizard UI (frontend via CDN, see above)
skills/ai-report/     SKILL.md — the summarisation methodology and output spec
mcp/                  client setup guides
docs/                 data-source adapters, and the full build prompts for this project
examples/             connector_template.py
scripts/              Windows one-click scripts
tests/                unittest suite
run_mcp_stdio.py      MCP stdio launcher (stable path for client configs)
reports/              generated reports (auto-created, gitignored)
templates/            learned format templates + archived samples (auto-created, gitignored)
trims.json            guide-page time trims (auto-created, gitignored)

Tests

python -m unittest discover -s tests -t .

Contributing

• New data source — see docs/数据源适配.md (Chinese) and the template in examples/connector_template.py
• Different report style — edit the output spec in skills/ai-report/SKILL.md
• Rebuild from scratch — docs/BUILD_PROMPTS.md is the full prompt set that produced this project

License

MIT