DEV Community

Paul Chen
Paul Chen

Posted on

Synthadoc: Your Coding Tool Is Now Your Wiki Brain

#ai #productivity #showdev #tooling

If you use Claude Code or Opencode, you are already paying for an LLM subscription.

Before v0.3.0, running Synthadoc also required a separate API key - Anthropic, OpenAI, Gemini, or one of the others.

v0.3.0 removes that requirement. Set provider = "claude-code" in one config file and your coding tool subscription becomes the brain of your personal wiki. No additional API key. No additional cost.

Why This Matters Beyond Convenience

The obvious win is billing consolidation. But there is a more interesting point underneath it.

Coding tools like Claude Code and Opencode started as pair programmers. They answer questions about your codebase. They write functions, fix bugs, explain unfamiliar code. That is what the marketing says.

What they actually are is a general-purpose LLM with a subscription model - capable of anything the underlying model can do, not just code. The coding framing is a UI convention, not a capability limit.

Synthadoc v0.3.0 makes that explicit. The same Claude subscription you use to navigate a TypeScript monorepo can now synthesize your research documents, detect contradictions in your notes, and answer structured questions about your domain knowledge. The subscription becomes infrastructure, not a point tool.

This is the same pattern that made cloud storage interesting once it stopped being "backup for photos" and became "filesystem for any application." The value is in the generality.

How It Works

Synthadoc's LLM providers are abstracted behind a single LLMProvider interface. Every agent - IngestAgent, QueryAgent, LintAgent - calls provider.complete() and receives a structured response. The provider implementation handles everything underneath: API calls, authentication, response parsing, error handling, quota detection.

For cloud APIs (Anthropic, OpenAI, Gemini), the provider sends an HTTP request. For Claude Code and Opencode, a new CodingToolCLIProvider class takes a different route: it launches the CLI tool as a subprocess, passes the prompt via stdin, reads the response from stdout, and parses the output.

# .synthadoc/config.toml
[agents]
default = { provider = "claude-code" }
lint    = { provider = "claude-code" }
Enter fullscreen mode Exit fullscreen mode

That is the entire configuration change. No API keys to set. No environment variables.

The server also accepts a runtime override:

synthadoc serve -w my-wiki --provider claude-code
Enter fullscreen mode Exit fullscreen mode

This overrides config.toml for the lifetime of the server process - useful for quickly switching providers without editing files.

Figure 1 - All agents share one provider interface. CLI providers slot in without changing anything else in the stack.

What Works, What Does Not

The CLI provider route is not a perfect substitute for a direct API connection. Two limitations matter:

No vector embeddings. Synthadoc's optional semantic re-ranking (hybrid BM25 + vector search) requires an embed() call, which the CLI tools do not expose. When using a CLI provider, search falls back to BM25-only. For most wikis up to a few hundred pages, BM25 is fast and accurate - this only matters if you have enabled vector search and are running a large corpus.

Quota is shared. Your CLI provider subscription has a daily or session quota. Heavy ingest operations - batch-ingesting 50 documents, for example - consume from the same budget as your coding work. The engine detects quota exhaustion, permanently fails the job with a clear message, and does not retry. You resume after the quota resets.

Both are manageable trade-offs for a personal wiki. If you need vector search or are running a high-volume ingest, a direct API key is the better choice — pick from any of the eight providers based on your quality, vision, and budget requirements. If you want zero additional configuration and are comfortable with BM25 search, the CLI provider path is clean.

The Provider Landscape in v0.3.0

One of the quieter design decisions in Synthadoc is that the LLM provider is not baked into the product. You pick the one that fits your constraints:

Provider API Key Required Free Tier Vision Notes
Gemini Flash Yes 1M tokens/day, no credit card Yes Default; best free option
Groq Yes Rate-limited No Fast, good for text-only
Ollama No Fully local Model-dependent Runs on your machine
DeepSeek Yes No (cheap) No Very low cost per token
Anthropic Yes No Yes
OpenAI Yes No Yes
MiniMax Yes No Yes
Claude Code No Included with subscription No New in v0.3.0
Opencode No Included with subscription No New in v0.3.0

Figure 2 — Per-agent model routing from a single subscription. Ingest and query use Opus for synthesis quality; lint uses Haiku for speed and lower quota consumption. Two config lines; one bill.

DeepSeek is also new in v0.3.0 - routes through the OpenAI-compatible endpoint, very low cost per token for text-heavy ingest workloads, and the R1 reasoning model <think> tags are stripped automatically before the response reaches Synthadoc.

The point of this table is not that any one provider is the best. It is that you should not need to change your workflow to use the tool. If you are already set up with Anthropic for Claude Code, switching your wiki to the same provider takes one config line.

Quota Exhaustion and Reliability

One detail the implementation gets right: quota exhaustion is a permanent failure, not a retryable one.

Most LLM API errors are transient - a timeout, a 5xx from an overloaded endpoint. Synthadoc retries those with exponential backoff. Quota exhaustion is different. Retrying a quota-exhausted call wastes the next request, then the one after that, burning whatever small remaining budget exists.

When a CodingToolCLIProvider detects that the subprocess output indicates quota exhaustion, it raises CodingToolQuotaExhaustedException. The orchestrator catches this and calls fail_permanent() on the job - no retries, no backoff. The job sits in failed state with a clear message: "Claude Code quota exhausted. Resume after quota resets." You do not return to find a queue of 50 failed retries.

Small detail. Meaningful when it happens.

Getting Started with Claude Code or Opencode Provider

Prerequisite: Claude Code or Opencode must already be installed and logged in on your machine. If not, follow the Claude Code setup guide or the Opencode setup guide first.

# 1. Clone and install
git clone https://github.com/axoviq-ai/synthadoc.git
cd synthadoc
pip3 install -e ".[dev]"
Enter fullscreen mode Exit fullscreen mode 
# 2. Install the demo wiki
# Linux / macOS
synthadoc install history-of-computing --target ~/wikis --demo

# Windows
synthadoc install history-of-computing --target %USERPROFILE%\wikis --demo

# 3. Set as the active wiki (no -w needed from here on)
synthadoc use history-of-computing
Enter fullscreen mode Exit fullscreen mode

4. Configure the CLI provider - edit ~/wikis/history-of-computing/.synthadoc/config.toml:

[agents]
default = { provider = "claude-code" }
Enter fullscreen mode Exit fullscreen mode

Or skip editing config.toml entirely and pass --provider at startup:

# 5. Start the engine - no API key needed
synthadoc serve --provider claude-code
Enter fullscreen mode Exit fullscreen mode

6. Install the Obsidian plugin - from the cloned synthadoc/ repo directory:

# Linux / macOS
cd ~/synthadoc   # or wherever you cloned it
vault=~/wikis/history-of-computing
mkdir -p "$vault/.obsidian/plugins/synthadoc"
cp obsidian-plugin/main.js obsidian-plugin/manifest.json "$vault/.obsidian/plugins/synthadoc/"

# Windows (cmd.exe)
cd %USERPROFILE%\synthadoc
mkdir "%USERPROFILE%\wikis\history-of-computing\.obsidian\plugins\synthadoc"
copy obsidian-plugin\main.js "%USERPROFILE%\wikis\history-of-computing\.obsidian\plugins\synthadoc\"
copy obsidian-plugin\manifest.json "%USERPROFILE%\wikis\history-of-computing\.obsidian\plugins\synthadoc\"
Enter fullscreen mode Exit fullscreen mode

Then in Obsidian: fully quit and reopen, then:

  1. Settings → Community plugins → Synthadoc → Enable, set Server URL to http://127.0.0.1:7070
  2. Settings → Community plugins → Browse → search "Dataview" → Install → Enable (required for the live dashboard)

The full configuration reference is in docs/design.md - Coding tool CLI providers.

What Else Is in v0.3.0

The CLI provider work is one piece of a larger release. v0.3.0 also ships:

  • YouTube video ingestion - paste a URL, get a structured wiki page with executive summary and [MM:SS] timestamped transcript
  • Web search fan-out - one search query decomposes into sub-questions, ingests multiple sources, builds cross-references automatically
  • CJK multilingual support - Chinese, Japanese, and Korean queries no longer trigger false knowledge-gap reports
  • Knowledge gap detection hardening - signal 5 redesigned for deterministic multi-aspect query scoring
  • DeepSeek provider - eighth provider, OpenAI-compatible, very low cost

Full release notes: github.com/axoviq-ai/synthadoc/releases/tag/v0.3.0.

Synthadoc is open source under AGPL-3.0 at github.com/axoviq-ai/synthadoc.

If you are already using Claude Code or Opencode daily, the marginal cost of running a structured personal wiki on top of the same subscription is zero. The marginal benefit compounds over time. That is a trade worth making.

Top comments (0)