Skip to main content
Read this page when you change a provider SDK, model list, streaming event, tool, or session. DocWriter supports Claude, OpenAI, Codex, Cursor, and Pi through one shared provider interface. Keep provider-specific details inside each adapter. Route open-tab edits through the document tools, preserve permission checks, and keep provider sessions separate.

​
Provider interface

src/lib/server/providers/types.ts defines AgentProvider. Each provider must:
  • Run a request and return a stream of ProviderEvent values.
  • List the models that DocWriter should show in settings.
Each adapter lives in src/lib/server/providers/. Add a provider to the ProviderId type and register it in src/lib/server/providers/index.ts. The render route only reads the common events. An adapter must convert its SDK output into events such as assistant text, tool calls, tool results, cost, status, and errors. The request options include an abortSignal. Claude and Codex pass that signal to their SDKs. OpenAI and Cursor do not currently use it. Pi stops yielding events after cancellation, but its underlying request may continue.

​
Document tools

An agent must not edit an open tab through a normal file write. Open tab reads and proposals go through the docwriter-doc tools in src/lib/server/mcp-doc-tools.ts. The tools connect to the live Hocuspocus document, so every browser receives the pending review. Normal file tools are still used for agent scratch files under .docwriter/agent/scratch/. The path router decides which path is an open tab and which path is scratch space. Use the shared permission wrapper in src/lib/server/providers/shared.ts when an SDK needs local tool definitions. The wrapper applies the allowed tool list and asks the permission callback before a tool runs. The propose_rule and propose_hook tools create items for the user to review. Keep that review step when you expose the tools through another provider.

​
Sessions

Providers do not all resume conversations in the same way. Claude can resume a native provider session. Other providers use their SDK session data or the conversation events saved by DocWriter. Keep provider session details behind the adapter. When a user switches providers, DocWriter clears the active provider session identifier so one provider cannot receive another provider’s session.

​
Skills and reviewers

Some SDKs can load skills or start subagents themselves. For providers without those features, DocWriter adds the needed instructions to the prompt or uses local tool handlers. A critique pass asks the main agent to run one reviewer. Every comment and review created during the pass receives the reviewer identifier, so the browser can show who made it.

​
Check a provider change

Run npm run check and npm run build. Then run the smoke test for the provider you changed:
Replace claude with the provider you changed. The smoke test needs valid credentials for that provider. Do not add credentials to the repository. A successful smoke test creates a pending review and receives the expected assistant reply. Cancel a request by hand and confirm that DocWriter closes the run. For Claude and Codex, also confirm that the SDK request stops. Switch to another provider and confirm that the new request does not resume the prior provider’s session.