CodePapr Tutorial

Design notes

• Local-first: files and commands run in the workspace
• Single runtime: Agent, Session, ToolRegistry, Provider share one semantics
• Cache-first: stable content first, volatile last
• Structured edits: Search/Replace diffs, validate then write

Supported LLM Providers

Requirements

Standard Installation

# After cloning the repository
npm install
npm run build

The desktop build (cargo check / npm run debug / release / publish) pulls tree-sitter and language grammars from crates.io; it no longer depends on .cargo-vendor/* submodules. npm run build already compiles the codepapr-server host, leaving a usable host binary on disk; when the desktop starts, it launches that binary as a Tauri externalBin sidecar.

Installation Verification

npm run verify

Passing this step confirms that your machine at least satisfies: correctly installed Node dependencies, successful workspace build (including the codepapr-server compile), passing workspace tests, and passing Tauri cargo check.

Supported Platforms

Both platforms share the same Rust backend and frontend codebase; the release pipeline outputs dmg/msi installers simultaneously.

External Dependencies

Depending on your operations, you may also need:

• A valid model API key (DeepSeek / OpenAI / Claude or a local compatible endpoint)
• Chrome or a Chromium-compatible browser (for browser interaction and screenshots)
• VS Code (optional, for workspace tasks and debugging configuration)

Three Launch Modes

Configuration Storage Locations

Provider Modes

DeepSeek API Reference URL

# OpenAI format (used by DeepSeek provider by default)
https://api.deepseek.com/v1

CodePapr's DeepSeek provider always uses the OpenAI-compatible https://api.deepseek.com/v1. If you want to use the Anthropic protocol with DeepSeek, select Claude as the provider and set baseURL to DeepSeek's Anthropic-compatible endpoint.

Environment Variable Fallback Order

The desktop provider compatibility layer reads API keys in the following order:

1. DEEPSEEK_API_KEY
2. OPENAI_API_KEY
3. ANTHROPIC_API_KEY

App-Level Settings

Fast Model Routing

Three Steps to Start

1. API key, provider, model in settings
2. Pick a project folder
3. Ask / Plan / Agent / App

Shortest Path

npm install
npm run build
npm run debug

First Use Workflow

1. Open settings, fill in provider, model, and API key
2. Select a project folder
3. Choose the current task mode among Ask, Plan, Agent, and App
4. Enter a task description and let the agent execute or analyze
5. Review results in the file tree, editor, Git, and preview panels

Entry Points

Note: The three built-in sub-agents — Explore, Scout, and Mentor — can be enabled and configured in the desktop settings panel (Mentor tab); the internal Verifier / Compactor model tiers are configured in the Advanced tab (verifierModelTier / compactionModel) and are never exposed via the task tool.

Ask, Plan, Agent, and App are not different products but four working modes of the same Runtime.

Ask Analysis Mode

Best for: Explaining architecture, clarifying module responsibilities, analyzing error causes, asking questions before deciding whether to execute.

Characteristics:

• Read-only: mutating tools (write/edit/bash/git, etc.) are blocked at the tool-registration layer, preventing accidental file changes by construction
• For time-sensitive questions, prefers read-only time/web tools for verification
• Only enters the read-only toolchain when you explicitly request project-based verification

Plan Planning Mode

Best for: Producing execution plans before large changes, confirming affected files and verification approach, breaking complex tasks into clear steps.

Characteristics:

• Provides a task checklist and implementation strategy first
• Analyzes affected files, execution order, verification methods, and potential risks
• When requirements are ambiguous, invokes the question tool to clarify decisions with the user

Agent Execution Mode

Best for: Fixing bugs, implementing features, running tests and verification, tasks that require actual file read/write and tool invocation.

Characteristics:

• Actively searches projects, reads/writes files, runs commands, performs verification
• Uses workspace tools, bash command execution, preview, and browser capabilities
• The main Agent execution loop runs in a Web Worker; long tasks won't block the UI
• Long-running commands like bash display execution status and logs in tool call cards
• Main execution defaults to a maximum of 500 consecutive internal tool rounds
• After file changes, background diagnostics are dispatched asynchronously; identical failure fingerprints won't trigger repeated fixes

App Application Generation Mode

Best for: Data exploration and visualization, generating interactive charts and dashboards, turning analysis results into interactive apps with a single sentence.

Core Philosophy:

• Your output is not a Markdown answer — it is a complete app (a split-file .papr app)
• Like instantly building a purpose-built tool for the current problem
• Fundamentally different from the coding Agent — it's an "app factory," not a "code writer"

Workflow:

1. Explore data: use list / read / grep to understand data structure
2. Write the app: use write to save manifest.json, a shell index.html, css/theme.css, and js/*.js split by responsibility under .CodePapr/apps/<appId>/
3. Open it: call app_render({ appId }) to mount it in the right-side Application panel (does not write files)

App conventions:

• Split files: index.html is a shell only; styles in css/theme.css; logic in js/*.js by responsibility (native ES modules, no bundler)
• Reference chart libraries via CDN (D3, ECharts, Mermaid, MapLibre, Leaflet, Three.js, etc.)
• Runs in a sandboxed iframe (sandbox="allow-scripts allow-same-origin")
• Use Papr SDK (window.papr) to call Agent, storage, HTTP, and filesystem capabilities
• Kanban/canvas apps that should receive coding-Agent pushes declare inbox in the manifest and subscribe with papr.events.on(channel, cb) — the contract is copied into session context "## Enabled plugins"; Agent mode calls app_publish from that catalog (do not use app_list); history replays via papr.db.get('inbox:<channel>'). Self-refreshing widgets must not declare inbox.
• papr.agent.run uses a 300-second idle timeout: as long as the Agent keeps emitting progress events (streaming output / tool calls) it can run indefinitely; only 300s of total silence triggers a timeout. Tool rounds are bounded by maxToolRounds (default/cap 50; search calls count toward the total)
• appId must be kebab-case; after editing files call app_render({ appId }) again to refresh — supports iterative refinement

Session Isolation:

• App and coding modes (Ask/Plan/Agent) are session-level isolated - once App is selected, the session is locked to App 🔒, cannot switch to other modes
• Coding sessions hide the App option - a session that started coding cannot switch to App
• Ask / Plan / Agent can switch freely between each other without creating a new session
• App ↔ coding mode switch -> create a new session

Model Strategy: Always uses the primary model to ensure app generation quality.

App Management: The right panel's "Apps" tab shows all registered .papr apps. Green/red dots indicate running status. Bottom toolbar: ▶ Start / Open / ■ Stop / 🗑 Delete. LLM manages app lifecycle via app_list, app_start, app_stop, app_delete tools. For full development and plugin specifications, see the App Mode & Plugin Generation section.

Permission model: Apps declare access with local (none / read / write) × network (true / false). Settings → App Tab can narrow the global default and per-app overrides; saving restarts running backends with the new sandbox.

App Mode Example Scenarios

• Database analysis: "Analyze this SQLite schema and generate a Database Explorer"
• Relationship diagrams: "Make a D3 force-directed graph of character relationships"
• Stock dashboards: "Generate a dashboard with candlestick charts and order flow"
• Document analysis: "Analyze paper-map — citation network, author relationships, topic clusters"
• Geo-visualization: "Analyze the geographic distribution of Tang Dynasty chancellors as a zoomable map"

How to Write Effective Tasks

CodePapr's actual performance depends heavily on task description quality. The most effective prompts typically include:

• What is the goal
• Where is the scope of changes
• Where is the reference implementation
• What must not be touched
• What are the verification criteria

Recommended Style

Fix the issue in packages/@codepapr/ui where background processes aren't stopped after preview closes.
First find the binding logic between the current preview session and background processes, then make a minimal fix.
After the change, at least run verification for the affected scope; if no narrow verification exists, explain why.

Less Effective Style

Help me fix the preview.

Interface Structure

• Left: Session list and quick access
• Center: Chat area showing messages, tool calls, status, and execution summaries
• Right: File tree and code preview
• Auxiliary areas: Git panel, background processes, web preview

Full Desktop Capabilities

Code Review Panel

Click Review in the top AgentOps toolbar to open the Code Review panel:

• Default diff compares HEAD~1..HEAD
• Left file list shows added/modified/deleted/renamed files
• Monaco diff editor displays both original / modified sides
• Click the line number gutter on either side to add line-level comments
• Comments can be marked as resolved / unresolved
• Overall review status can be set: Pending Review / Approved / Changes Requested / Commented

Round Navigation

A compact indicator bar on the right edge of the chat area shows one tick per user message:

• Hover the bar → panel opens, listing all rounds (#1 number + user's first sentence)
• The currently visible round is highlighted in both the bar and panel
• Click any round → smooth-scroll to that message
• Panel auto-closes when mouse leaves (200ms delay to prevent accidental dismiss)

Global Search

The toolbar search box supports both conversation and file search via Chat | Files tabs:

• Chat tab: Search current session messages, filter by role (All / You / AI), ↑↓ navigate Enter jump
• Files tab — Content mode: Search file contents across the workspace, results show path + line + matching line
• Files tab — Filename mode: Search file paths and names
• Click a file result → open the file and jump to the matching line in the editor
• Results panel is viewport-centered, 300ms debounced, backend search only runs when Files tab is active

Toast Notifications

The desktop uses non-blocking toasts instead of alerts:

• Four colors: info / success / warning / error
• Default 4.5 seconds auto-dismiss; error defaults to 8 seconds
• Maximum 5 simultaneously displayed; drops the oldest when exceeded

External Path Permissions

When the Agent requests to read or list absolute paths outside the project, the desktop shows a permission dialog:

• Deny: Block this access
• Allow this file: Only permit this file
• Allow this folder: Permit this directory and its children

Authorization results are saved in a whitelist; subsequent accesses to the same path won't trigger the dialog again. Write, edit, and command execution remain restricted to the workspace.

When to Prefer the Desktop

• You are doing multi-round fixes or refactoring
• You need to see the file tree while the agent works
• You need Git diff, page preview, or page automation
• You want to consolidate sessions, files, and verification in one interface

Git Integration

• Git Panel: Shows staged/unstaged diff, recent commit history, branch creation/switch, local commits, safe discard of local changes
• 8 Agent Git Tools: status, diff, history, branch_checkout, stage, commit, restore, reset — all powered by built-in libgit2 Tauri commands (no system git required)
• Auto-init: If the workspace doesn't have a Git repo yet, the panel can initialize one via built-in libgit2 (no system git required)

Conversation Reset (Shadow Git Snapshot)

Before each user message, CodePapr captures a code snapshot via its own internal Shadow Git repo at .CodePapr/git/ (powered by libgit2 — no system Git CLI required):

• IgnoreResolver scans the workspace file tree, respecting .gitignore and auto-excluding node_modules/, dist/, .next/, large files (>100MB), etc.
• Files are added one-by-one via index.add_path and committed as checkpoint #N · "message preview"

When you need to roll back:

• Hover over any user message and click "Reset to here"
• Restore Plan: CodePapr computes exactly which files will change — showing you the count of files to restore/delete/unchanged before executing anything
• Execute: After confirmation, the system resets to the checkpoint snapshot
• A backup ref refs/codepapr-backup-before-reset is created automatically — you can undo the reset anytime
• The message list is synchronously truncated; all subsequent conversation is removed

The Agent registers a comprehensive toolset covering file operations, ProjectGraph analysis, Git, preview, browser, Shell, LSP, and all local development scenarios. Below are the key tools grouped by capability.

graph — Core Project Understanding

A unified project semantic graph tool that selects operations via the action parameter. Simultaneously returns a directory tree, code structure skeleton, and file/symbol relationship graph, serving as the foundation for all symbol lookup, dependency analysis, and impact analysis.

File Operations

LSP Language Intelligence

Command Execution

Git Operations

Browser & Preview

App Render

Web Tools

Other Tools

External Path Permissions

In the desktop, read / list operations on absolute paths outside the project trigger a PermissionDialog popup for authorization; writes remain restricted to the workspace. For a file directly under the filesystem root, choosing "Allow this folder" is automatically downgraded to granting that single file only, so one click can never grant the entire filesystem root.

File Size Limits

A single read / write / edit / patch operation is capped at 20MB, covering most source code and binary resource files, though large files will significantly increase token consumption.

Experimental feature, off by default: enable "Characters" under Settings → General → Experimental features to reveal the toolbar entry. CodePapr supports creating, importing, and managing AI characters, allowing the Agent to converse with you in a specific persona. Once enabled, the profile is injected into the Session Bootstrap (assembled in promptBuilders.ts / characterTypes.ts), not core promptSystem.ts and not ImmutablePrefix.

Character Data Model

Each character includes the following fields:

Roleplay Format Conventions (roleplay mode only)

In roleplay mode, the system prompt specifies the following format rules so TTS can correctly distinguish dialogue from actions. In Ask / Plan modes the character is always injected as a coding persona and this format does not apply:

Creating a Character

1. Click the Character Button (avatar icon) in the toolbar to open the character management panel
2. Click "New Character"
3. In the Basic tab, fill in name, description, personality, scenario, first message, example dialogues, etc.
4. Optionally upload an avatar image (PNG/JPG)
5. In the Voice tab, configure voice synthesis (optional; see next section)
6. Click Save

Importing Character Cards (CCv3 / SillyTavern Compatible)

CodePapr is compatible with the chara-card-v3 specification and can import characters from other tools:

1. Click the "Import Character Card" button in the character panel
2. Select a PNG file (JSON embedded in the image's tEXt/iTXt chunk) or a JSON file
3. Character information is automatically parsed; PNG images are automatically set as avatars
4. Review and adjust the imported fields, then click save

Supported PNG chunk keywords: chara, ccv3, character, character_card

Exporting Character Cards

Click a character's Export button in the character list to export it as a PNG character card. The PNG embeds the complete CCv3 JSON and can be used in tools like SillyTavern. Portable voice settings (speed, sample steps, sentences per chunk, playback mode, languages) are written to extensions.codepapr.voice; local reference-audio and fine-tuned-model file paths are not exported with the card.

Activating/Switching Characters

Click Enable on the editor to apply the character to the current session only; unsaved edits in the panel are saved automatically first. Clicking a name in the list opens it for editing and does not activate it. Opening the panel selects the character already enabled for this session. In an empty session, switching characters replaces the previous character's greeting with the new one.

Character personas are placed in the Session Bootstrap (not in the system prompt's ImmutablePrefix), so switching characters does not break the LLM prefix cache. In Ask / Plan modes the character is always injected as a coding persona; the roleplay format only applies in Agent mode. New sessions start with no character.

Experimental feature, off by default: enable "Voice" under Settings → General → Experimental features to reveal voice controls; auto-read also requires "Characters" enabled with voice configured on the active character. CodePapr integrates the GPT-SoVITS voice cloning engine, capable of synthesizing a character's text replies into speech locally. Only 3-10 seconds of reference audio are needed to clone a character's voice.

Installing GPT-SoVITS

First-time voice usage requires installing GPT-SoVITS. There are two installation entry points:

• Click the TTS speaker button on the ChatPanel; if not installed, an installation wizard will auto-launch
• Trigger installation in the Voice Tab of the character editing panel

The installation wizard auto-completes 5 steps: check Python → clone GPT-SoVITS repository → pip install dependencies → download pretrained models (about 2GB, using hf-mirror source) → verify.

Requires Python 3.10+ already installed on the system. The installation process writes to ~/.codepapr/gpt-sovits/.

Configuring Voice for a Character

1. Click the Character Avatar Button in the toolbar to open the character editing panel
2. Switch to the Voice Tab
3. Upload Reference Audio:
   • Duration 3-10 seconds (5 seconds recommended); too short gives poor cloning, too long gets truncated
   • Format WAV / MP3 / M4A / AAC; sample rate 16kHz or higher
   • Content: clear human voice, no background music, noise, or reverb
4. Fill in Reference Text: must match the audio content word-for-word; otherwise cloning quality will be poor
5. Select Reference Audio Language and Speaking Language (supports Chinese, Cantonese, English, Japanese, Korean, and mixed modes)
6. Adjust parameters:
   • Speed: 50% - 200%
   • Synthesis Speed: only 4 / 8 / 16 tiers. 4=fastest, 8=balanced, 16=highest quality
   • Merge Sentences: 1-5, merge this many sentences in one synthesis batch to reduce round trips
   • Playback Mode: defaults to ws-batch; streamed-pipeline / streamed-pcm / whole also selectable
7. Click the "Preview" button to preview the effect
8. Flip the "Enable Voice Output" switch (it refuses to turn on while the reference audio or reference text is missing), then click Save

Playback Modes

The Voice Tab exposes four playback modes. The default and recommended one is WebSocket batch streaming (ws-batch): sentences are first merged into chunks per the "Merge Sentences" setting (3 by default), then each chunk is sent over a single persistent WebSocket connection and returned one by one, with first-word latency around 1-2 seconds and smooth inter-sentence transitions.

The other three: streamed-pipeline / streamed-pcm (per-sentence HTTP requests with PCM pushed straight to the player; best compatibility) and whole (waits for the complete reply, then synthesizes and plays it in one go; slowest start but the most coherent).

Voice Fine-tuning

For higher audio quality requirements, use the fine-tuning feature in the Voice Tab:

1. Ensure reference audio and reference text are configured and the preview passes
2. Click "Generate Training Data": the LLM generates about 500 words of dialogue script based on the character setting; GPT-SoVITS auto-synthesizes about 2 minutes of training audio, no manual recording needed
3. Click "Start Fine-tuning": background training, typically 30-60 minutes; you can close the window
4. After training completes, check "Use Fine-tuned Model": timbre is more stable, synthesis is faster, synthesis speed can drop to 4 (fastest tier)

Playback Controls

• Auto-read: Characters with voice enabled will auto-read their AI replies aloud
• Replay: Hover over any AI reply to see a “Replay” button to re-read that message
• Stop: Canceling the current Agent message will interrupt ongoing reading
• Service Control: The TTS speaker button on the ChatPanel starts the GPT-SoVITS service or views service logs/status

.CodePapr/AGENTS.md — Global Project Rules

Project-wide rules are injected into the main Agent and all sub-agents. Good for:

• Code style and directory conventions
• Build, test, and release commands
• Paths or behaviors that must not be changed
• Project background and acceptance criteria

Memory panel — cross-session project memory

Cross-session memory is a single file in your workspace, .CodePapr/MEMORY.md (three sections: user preferences & constraints / tech stack & environment / architecture & known facts) — readable, diffable, git-friendly. The built-in memory curator (internal subagent) maintains it in the background, and the memory panel is its editor. Layers and timing: Context layering.

• Two checkpoints: delivery (end of turn; runs only when your message carries a memory cue — remember / must / never / always — or the turn has a verified test/build command) and pre-compaction (runs unconditionally before any compaction commit, 20s timeout).
• Write boundary: the curator only sees the turn's user text plus the assistant's final text (skeleton when pre-compaction) — never raw tool output; secrets are redacted and injection / dangerous commands / oversized content / “drop-more-than-half” edits are rejected.
• The Agent does not write memory: memory_write / memory_search / memory_list / memory_forget are retired; direct writes to MEMORY.md are intercepted and rejected — the Agent states durable facts in its answer instead.
• When it reaches the model: every turn reads the file into session bootstrap — a saved change takes effect next turn (a one-time prefix miss), panel edits included.

/compact — Force Context Compression

Manually trigger v4 skeleton compaction, folding older rounds into a checkpoint to free token space:

• Force mode: bypasses the 90% trigger line (an ineffective shrink is still rejected — no no-op checkpoints)
• Deterministic skeleton: each folded round keeps its user question + final summary as two lines; tool calls/results collapse into count notes — zero LLM. The most recent 5 rounds stay verbatim; the zero-tool Compactor runs once only if the skeleton still overflows (deterministic line-truncation fallback otherwise)
• Refreshes session bootstrap: the memory curator runs before compaction (folding what is about to be folded), then the bootstrap is re-rendered — new memory takes effect with the epoch
• Use case: When approaching context limits or responses slow down, compress to restore smooth conversation

Configuration Entry Points

The "Config" entry in the desktop project header can:

• Create/edit .CodePapr/AGENTS.md (generates a default template if none exists)
• Create/edit/delete custom sub-agents (.CodePapr/agents/*.md)
• Create/edit/enable/disable/delete Skills (.CodePapr/skills/**/SKILL.md)

Data Location Overview

Search/Replace Diff (YOLO Diff)

CodePapr's automated modifications do not rely on standard Git diff line numbers. Multiple localized modifications are preferentially generated as Search/Replace blocks:

<<<<<<< SEARCH
Existing code already in the file
=======
Replacement new code
>>>>>>> REPLACE

Application Rules

• SEARCH must exactly match content in the target file
• If the same SEARCH matches multiple locations, it is rejected to prevent unintended changes
• A single batch modification validates all files and all blocks first; if any block fails, no file is written
• Line endings are compatible with LF / CRLF
• Failure information is fed back to the Agent context, triggering a re-read of the original file and self-healing retry

Recommended Use Cases

• Localized modifications across multiple files
• Fixing tests, lint, or type errors where context precision must be maintained
• Agent mode requiring a machine-parseable, verifiable, and rollback-friendly modification format

Not Recommended For

• Creating new files or full file rewrites → use the write file tool
• Changing only a very small localized block → regular patch is more direct

What is a Skill

A Skill is the main Agent's reusable operations manual, suitable for codifying search strategies, troubleshooting workflows, release checklists, review manifests, and project-specific working methods. It does not create an independent sub-agent but serves as project-level context for the model to select on demand.

Skill File Format

Organized as directory packages, placed under .CodePapr/skills/**/SKILL.md. Each directory can contain assets/, references/, scripts/, and other resources.

---
name: search
description: Conduct verifiable searches using public web, official docs, and community resources
---

# Search Skill

When a task requires public information, current facts, third-party API usage, or error troubleshooting:

- Official docs first, then GitHub issues/PRs, then community answers.
- Use double quotes for exact error strings, e.g. "Cannot find module".
- Limit to specific sites using site:, e.g. site:developer.mozilla.org fetch abort.
- Include the library name, version, runtime environment, and key error codes together.

Skill Loading Mechanism

• At runtime, only the name + description of user-enabled Skills are injected into stable context
• The model decides autonomously whether a Skill is needed
• Only after selection is skill called to read the full content
• Enable status is saved in .CodePapr/project.sqlite

Built-in search Skill

The default search Skill includes common reference sources and methods:

• Official Documentation: Microsoft Learn, OpenAI, MDN, Node.js, npm, PyPI, Rust, Tauri, Vite, React
• Code & Issues: GitHub repositories, issues, pull requests
• Community Resources: Stack Overflow, package manager pages, maintainer blogs
• Search Methods: site: to scope to a domain, double quotes for exact errors, package name plus version number

Built-in Sub-agents

CodePapr comes with three built-in sub-agents that the main Agent can dispatch via the task tool without additional configuration:

* Mentor uses the primary model by default; an independent mentor model can be enabled in settings (supports independent API Key, Base URL, and model selection; falls back to the main API Key when no dedicated key is configured).

Runtime-Internal Agents (never exposed via the task tool)

All three internal agents are internal: true, invoked directly by the runtime: Verifier by the GoalRunner acceptance loop (dedicated budget: 6 tool rounds / 3-minute wall clock); Compactor by the compaction pipeline when the skeleton still overflows; Memory-curator by the memory pipeline at the delivery / pre-compaction checkpoints (its material never contains raw tool output). All three are zero-tool and get no skills/memory/project-graph injection (bootstrap isolation), with the sub-agent default 20-minute wall clock. In v4 the main compaction path is the deterministic skeleton (zero LLM); the Compactor runs only as a single second-level summary, falling back to deterministic line truncation when the fast tier is selected but the fast model is disabled — never recursion.

Custom Sub-agents

Declare a sub-agent in .CodePapr/agents/<name>.md with YAML frontmatter + body. The main agent can delegate subtasks to it. An agent with the same name will override the built-in definition.

---
description: reviewer is responsible for reviewing current changes, identifying risks, and providing minimal fix suggestions
mode: subagent
model: fast
temperature: 0.2
tools:
  read: true
  grep: true
  diagnostics: true
  git: true
  write: false
  exec: false
---

You are reviewer, a read-only code review sub-agent.

Responsibilities:
- Read the goal, relevant files, and current diff delegated by the main agent.
- Prioritize finding real bugs, behavioral regressions, missing edge-case handling, and absent verification.
- Provide minimal fix suggestions, indicating which files to modify and what verification commands to run.

Boundaries:
- Do not directly modify files by default.
- Do not repeatedly summarize irrelevant code style; only report findings that affect correctness, reliability, or maintainability.

Output Format:
1. Findings: List issues by severity
2. Suggested Fix: Provide the minimal fix direction
3. Verification: List recommended verification commands

Sub-agent Configuration Reference

• model: Override model; options: fast (fast model) or a specific model name
• temperature: Temperature parameter; optional numeric value
• tools: Tool switches; defaults to inheriting all tools; declaring an empty object {} means no tools
• The filename (without .md) is the sub-agent name; same name overrides built-in agents
• Modify description to tell the main agent when to invoke it
• Modify tools to control read/write/command permissions

Sub-task Mechanism (Two Approaches)

Sub-agent Runtime Model

• Each sub-agent has an independent Session, ToolRegistry (filtered by tools), and Provider
• Maximum nesting depth: 2 levels (sub-agents cannot delegate to other sub-agents)
• Sub-agents can execute up to 50 internal tool rounds (main agent: 500)
• Individual tool calls have a 90-second timeout — errors are returned to the LLM for autonomous decision
• Each sub-agent has a 5-minute overall wall-clock timeout with automatic cancellation
• Explore and Scout use the fast model; Mentor uses the independent mentor model or primary model
• Custom prompts can be overridden in the Mentor tab of the settings panel

Difference from AGENTS.md

.CodePapr/AGENTS.md contains global project rules inherited by all modes and all sub-agents; custom Agents are dedicated sub-agents, only activated when the main Agent delegates sub-tasks via the task tool. The former is for writing "what all tasks must comply with," the latter for "who handles a certain type of task and which tools they can use."

Built-in Commands

Commands support both --name (recommended) and /name (legacy compatibility) formats. A command's model field determines routing: undeclared uses the primary model, fast uses the fast model, and local commands cost zero tokens.

Custom Command Templates & Syntax

Declare reusable prompt templates in .CodePapr/commands/<name>.md to register slash commands /<name>:

Practical Template Examples

Example 1: Static Page & Rendering Logic Diagnosis (Zero Git Risk)

---
description: Diagnose index.html structure and visual logic
usage: /pagecheck [observed issue]
model: fast
---
Please help diagnose the page structure and visual logic of this static project.
Page entrypoint: @index.html
User question: $ARGUMENTS

Example 2: Dependency & Script Analysis

---
description: Analyze package.json dependencies and scripts
model: fast
---
Please answer user question based on root config:
Config: @package.json
Question: $ARGUMENTS

Example 3: Code Review & Lint Fix (Delegate to Subagent + Live Status)

---
description: Review and fix lint
agent: code-reviewer
---
Please review the changes for $ARGUMENTS and fix any lint issues.
See rules at @.CodePapr/AGENTS.md
Current status: !`git status -s`

What is App Mode and .papr Apps

In CodePapr, App mode is not merely a code assistant — it is an on-demand interactive application factory. Simply describe what you need in natural language, and the Agent explores data, designs architecture, and builds ready-to-use .papr applications or desktop plugins in seconds, mounting them directly in the main window.

Two Artifact Forms: Fullscreen Apps vs. Desktop Plugins

Every .papr app declares its form via the kind field in manifest.json:

.papr Source Structure & Mandatory Modularization

All apps and plugins are stored in .CodePapr/apps/<appId>/. To allow precise patching and continuous iteration by the Agent, CodePapr mandates modular file organization (native ES Modules, zero build tools, import statements must include .js extensions):

.CodePapr/apps/<appId>/
├── manifest.json       # App manifest: metadata, kind, surface, permissions, inbox contracts, agents
├── index.html          # Shell HTML: skeletal markup only, loads CSS & js/main.js, no giant monoliths
├── css/
│   └── theme.css       # Theming & styling: supports html[data-mode="dark"] & html[data-mode="light"]
├── js/
│   ├── main.js         # Entry module: initialization, DOM binding, and event listeners
│   ├── db.js           # Key-value storage wrapper (papr.db)
│   ├── ui.js           # View rendering, loading states, and animations
│   ├── api.js          # External HTTP fetch wrapper (papr.http, optional)
│   └── agent.js        # Multi-turn AI Agent wrapper (papr.agent.run, optional)
├── data/               # App-private sandbox filesystem storage (papr.fs, created at runtime)
└── db.sqlite           # papr.db data & inbox history (created at runtime)

Note: For lightweight plugins (kind: "plugin"), a 3-file layout (index.html + css/theme.css + js/main.js) is recommended until any single file exceeds ~200 lines.

Papr SDK Capabilities (window.papr)

Apps run inside a secure sandboxed iframe. Without installing npm packages, the runtime automatically injects the window.papr SDK:

Agent Push Mechanism (app_publish + inbox Contract)

In "Agent writes code in terminal → Plugin visualizes progress/architecture in real time" collaboration workflows, CodePapr provides a zero-overhead publish/subscribe system:

1. Plugin Declares Contract: Declare inbox channels and minimal payload example in manifest.json.
2. Agent Auto-Discovery: Enabled inbox plugins are automatically surfaced in the coding Agent's session context under "## Enabled plugins".
3. Push from Any Mode: The coding Agent calls app_publish({ appId, channel, payload }) from any writable mode (Agent / Plan / App).
4. Dual-Channel Persistence & Replay: Events are atomically appended to the app's db.sqlite (up to 200 events retained); delivered live via papr://event if mounted; when unmounted events are briefly queued (~30s) so a freshly opening instance still receives them live, while later launches replay history using papr.db.get("inbox:<channel>") (live and replay can overlap — dedupe by seq).

Security & Permission Isolation Model

manifest.json uses a Local Access (local) × Network Access (network) matrix:

App Management Dock

Switch to the Apps tab on the right sidebar to browse all generated .papr apps and plugins:

• Status Indicators: Green dot indicates "Ready/Pinned", labeled with a Plugin badge for overlay widgets.
• Toolbar Actions:
  • Open / Pin / Unpin: Show floating overlay in the main window or hide it;
  • ▶ Run / ■ Stop: Manage lifecycle of apps running background server processes;
  • 🗑 Delete: Permanently delete app directory and runtime state;
  • ⤓ Export: Package app as a .zip for sharing and backup.
• Settings Overrides: In Settings → App tab, configure default access for undeclared apps or narrow permissions per app.

Practical Example 1: Live Crypto Ticker Floating Plugin

Prompt: "Generate a lightweight floating crypto ticker plugin in the top-right corner, showing BTC/ETH prices every 10s with compact typography."

manifest.json Configuration:

{
  "spec": "papr/0.1",
  "name": "Crypto Ticker",
  "version": "1.0.0",
  "kind": "plugin",
  "surface": {
    "type": "overlay",
    "width": 300,
    "height": 180,
    "position": "top-right"
  },
  "local": "none",
  "network": true
}

js/main.js Logic:

async function fetchPrices() {
  try {
    const data = await window.papr.http.get('https://api.coingecko.com/api/v3/simple/price?ids=bitcoin,ethereum&vs_currencies=usd&include_24hr_change=true');
    render(data);
  } catch (err) {
    console.error('Ticker error:', err);
  }
}

fetchPrices();
setInterval(fetchPrices, 10000);

Practical Example 2: Architecture Evolution Board (Agent Push Supported)

Prompt: "Generate an architecture evolution board plugin that subscribes to the cards channel to receive live task nodes as you code."

manifest.json Configuration (with inbox contract):

{
  "spec": "papr/0.1",
  "name": "Architecture Board",
  "kind": "plugin",
  "surface": {
    "type": "overlay",
    "width": 360,
    "height": 260,
    "position": "bottom-right"
  },
  "local": "none",
  "network": false,
  "inbox": {
    "cards": {
      "description": "Push task progress & state change cards",
      "example": { "id": "task-1", "title": "Refactor Auth", "status": "done" }
    }
  }
}

js/main.js Subscription & History Replay:

// 1. Replay historical events on startup
const history = await window.papr.db.get('inbox:cards') || [];
history.forEach(evt => applyCard(evt.payload));

// 2. Listen to live Agent push events
window.papr.events.on('cards', (evt) => {
  applyCard(evt.payload);
});

Practical Example 3: Fullscreen SQLite Database Explorer (Full App)

Prompt: "Analyze the stats.sqlite database in this project and generate a fullscreen Database Explorer app with paginated table views and SQL query execution."

The Agent declares local: "read", modularly splits frontend components and SQL result tables, and mounts a full interactive dashboard in the workspace Apps panel.

What is the Goal Loop

/goal is a control command (same level as /compact) that starts a Worker + Evaluator dual-model autonomous loop. It transforms the AI coding assistant from a single-turn Q&A mode into a long-running autonomous agent that continues until a machine-verifiable condition is satisfied.

The core mechanism is not adding "keep working until done" to the prompt — it's an engineered self-play system:

• Worker (primary model): has full tool permissions, responsible for planning, writing code, running tests
• Verifier (read-only sub-agent: read/grep/glob/list): reads the Worker's execution transcript and can independently verify files, determines if success is being fabricated
• Objective condition function: executes verification commands, uses exit codes and output matching for objective judgment

The three work together: condition function + Verifier anti-forgery = double insurance. Only when the condition is met AND the Verifier confirms the Worker didn't cheat is it judged SATISFIED.

Basic Usage

# Exit code 0 satisfies the condition
/goal exec:npm test

# Exit code 0 AND stdout matches regex
/goal exec:npm test match:"\d+ passed"

# Compound condition, all must pass
/goal exec:npm run lint && exec:npm test

# Natural language goal + verification condition (| separator)
/goal fix auth tests | exec:npm test

Condition Syntax

How It Works

1. Worker turn: the main Agent executes one round of work (read files, write code, run commands)
2. Objective condition evaluation: the system automatically runs the verification command and gets exit code + output
3. Verifier anti-forgery check: the read-only Verifier sub-agent (read/grep/glob/list) reads the Worker's execution transcript and independently verifies key claims with its tools, detecting completion bias like "claiming tests pass without actually running them"
4. Judgment: condition met AND Verifier confirms → SATISFIED, loop ends; otherwise detailed feedback is injected into the next round
5. Context rot mitigation: auto-compaction every 5 iterations through the same epoch commit as between-turn compaction (insert checkpoint, re-render and prime the bootstrap, rebuild the agent in place, await the single-transaction commit) — the Goal runtime context actually shrinks; state persisted to .CodePapr/goal-state.md

Safety Guardrails

Configuration

Configure Goal loop parameters in the Advanced tab of the settings panel:

• Max iterations: default 20, adjustable 1-100
• Max wall clock: default 30 minutes, configured in minutes
• Verifier model: default fast model (faster, cheaper), switchable to primary model (more accurate)
• Verifier token limit: default 4000
• Verifier temperature: default 0.1 (lower is more deterministic)

What is MCP

The Model Context Protocol (MCP) is an open protocol that allows Agents to extend their capabilities through external tool servers. CodePapr includes a built-in MCP host that can connect to multiple MCP servers simultaneously, exposing external tools to the main Agent for invocation.

Each MCP tool is registered in the form mcp__<serverId>__<toolName>, appearing alongside the 30 built-in tools in the ToolRegistry.

Three Transport Modes

Per-MCP Server Fields

Preset Examples

The desktop provides three ready-to-use MCP servers by default (all disabled; must be manually enabled):

stdio Server Example

# Name
DuckDuckGo Search MCP

# Transport
stdio

# Command / Arguments
command: npx
args: -y duckduckgo-mcp-server

# Environment variables (one KEY=value per line)
env:
HTTP_PROXY=http://127.0.0.1:7890
USER_AGENT=CodePapr/0.1.0

# Tool filtering
allowedTools: duckduckgo_web_search

sse / streamable-http Server Example

# Name
Remote Knowledge Base

# Transport
streamable-http

# URL
url: https://example.com/mcp

# Headers (one Header-Name: value per line)
headers:
Authorization: Bearer your-token-here
X-API-Key: your-api-key

Permission Modes

• read-only: Read-only tools, no confirmation required for invocation (suitable for search, queries)
• read-write: Writable tools, used with requireConfirmation
• dangerous: Dangerous tools (e.g., execute shell, delete data); strongly recommended to enable requireConfirmation

Tool Filtering

Control the subset of tools exposed by each server via allowedTools and deniedTools:

• Supports * wildcards (e.g. describe*, list_*)
• Comma-separated for multiple patterns
• Denylist takes priority over allowlist
• Typical scenario: Postgres MCP defaults to allowedTools=query,describe*,list* + deniedTools=delete*,drop*,truncate*,update*,insert*, ensuring read-only access

Global Switches

Recommended Common MCP Servers

• @modelcontextprotocol/server-filesystem: Restricted filesystem access
• @modelcontextprotocol/server-postgres: Postgres database
• @modelcontextprotocol/server-github: GitHub API
• @modelcontextprotocol/server-slack: Slack integration
• mcp-server-sqlite: SQLite database
• duckduckgo-mcp-server: Free web search

Architecture Overview

Package-Level Responsibilities

Host / Client Responsibilities

The Tauri desktop is not a monolithic backend: src-tauri keeps GUI-only capabilities and thin RPC proxies. File system, Git, Shell, LSP, database, MCP, Web, and other domain implementations live in codepapr-core and are exposed uniformly by codepapr-server over JSON-RPC.

• src-tauri/src/commands.rs: Tauri commands that proxy UI requests to host.rs
• src-tauri/src/host.rs: starts/connects to codepapr-server, sends JSON-RPC, and forwards notifications to the Tauri event bus
• crates/codepapr-server: RPC routing, parameter validation, event broadcasting, and task queue
• crates/codepapr-core: domain subsystems such as workspace_fs, git_operations, shell, lsp, db, mcp_host, and web
• GUI-only exceptions: embedded/headless browser, TTS, Stronghold vault, file export, and the Papr App runtime remain client-owned

Desktop Agent Bridge

The desktop does not invoke the core Agent directly; instead, it offloads the LLM chat loop into a Web Worker via WorkerBackedAgent, ensuring long tasks do not block the UI.

Worker Crash Recovery & Streaming Snapshots

• Crash capture: The main thread catches WorkerCrashError, automatically clears the current agent instance (next send creates a new Worker), and prepends "Agent Worker crashed." to the error message
• Streaming snapshots: During streaming responses, approximately every 2 seconds (STREAM_SNAPSHOT_INTERVAL_MS), onStreamSnapshot is triggered to persist in-flight content to the project SQLite
• Power-loss recovery: After a crash / forced quit / power loss, the next launch shows the conversation fragments written before the crash, preventing large chunks of progress from being lost

Tech Stack Overview

How a request is stacked (cache view)

The model does not get one blob. Full layering and memory flow: Context layering. Earlier bytes stay still so prefix cache works:

Cache Hit Patterns

Key Invariants

• User-custom prompts go into session bootstrap, not each round's user prompt
• Skills go into bootstrap, not the system prefix
• The workspace path only appears in the system prompt, not duplicated in bootstrap
• Custom guidance appears only once in bootstrap
• Session bootstrap follows the per-turn promptKey: MEMORY.md / skills / file changes rebuild once on the next turn (save now, effective next turn), otherwise it keeps hitting
• Per-turn dynamic content (date / diagnostics) is placed at the tail, not in the existing prefix

Cache-First Architecture: the Context Epoch Model

Prefix cache hits automatically by byte-exact prefix match (no explicit breakpoints). The first principle is: keep the prefix byte-stable (append-only) within an epoch; reset it deliberately only across epochs via compaction.

• An epoch = a span within one agent lifetime during which the prefix stays byte-stable. Each tool-loop round appends the assistant message and tool results to the tail; the prefix is reused byte-for-byte → the multiple calls within a loop naturally hit the cache.
• The epoch boundary = context compaction: when the context threshold is reached, history is summarized into a checkpoint + retained tail, starting a new epoch (a one-time miss, then stable hit accumulation resumes). This mirrors OpenCode's Context Epoch and Claude Code's auto-compact. The checkpoint is inserted at the retention boundary (not appended at the end); the recent tail after it stays verbatim (including tool-call↔result pairs — the boundary is chosen at UI-message granularity so no tool message is orphaned). In the effective context the checkpoint is emitted as a user turn, avoiding a leading/consecutive assistant after compaction for better cross-provider correctness.

Mid-Loop Overflow → Compaction

Context grows with tool results during the tool loop. Agent.chat estimates the context size before building each round's request; when the effective threshold is exceeded, it compacts (resetting the log into a new epoch) and continues:

• Round-start check only: tool results are appended at the end of a round; the overflow they cause is caught at the next round's start — no LLM request is ever sent with an over-limit context; the task continues after compaction from "summary + recent tail".
• No mid-tool-execution compaction: a round's multiple tool calls are executed atomically before compacting at the round boundary, preserving tool-call↔result pairing.
• Anti-loop: repeated ineffective/failed compactions trip a circuit breaker for the turn; after a successful compaction the log is below the threshold, so retries do not oscillate.
• Defense in depth: each tool result is first truncated to ~50KB (or spilled to disk with a preview), so per-round growth is bounded.

Pruning Is Retired (v4)

The old protection-window pruning layer was removed with v4: tool results now only exist inside the ≤5 most recent verbatim rounds — anything older is already folded by the skeleton, so separate pruning is meaningless. A single oversized tool output is bounded by the entry guardrails (tool-output truncation and artifact spillover, readable back via history_read_artifact). The trigger remains a single line: 90% of the context window.

Effective Context Threshold (single rule)

maxContextTokens declares the model input window (default 200K) and applies uniformly to DeepSeek, OpenAI-compatible, and Claude providers (no per-provider clamping). The compaction trigger line = window × 90% (constant COMPACT_TRIGGER_RATIO) — the same source for the main session, mid-loop, Goal, and task sub-agents; provider-measured usage and the estimate take the larger value, and genuinely over-limit requests still fall back to emergency compaction. A higher window → fewer compactions → higher hit rate (cache reads are cheap).

Prefix-Stability Guarantees

• No per-request prefix mutation: v4 has no sliding pruning; history is only ever rewritten at epoch boundaries
• Byte-identical rebuild serialization: object tool results use sortedStringify (matching the live path); empty assistant content is ''
• Stable reasoning round-trip: reasoning_content is round-tripped based on "presence + model capability", decoupled from the per-request thinking toggle
• Frozen TodoList digest: the current digest is frozen into the checkpoint at generation and reused on rebuild instead of re-rendered live
• Frozen parameters: topP / temperature / maxTokens / thinkingEnabled are frozen in ImmutablePrefix; any change flips the hash

Known limitations: LLM prefix cache has a lifetime; after a long idle period the first call re-misses the whole prefix (independent of the client). Compaction is lossy — the higher the threshold, the more history a single compaction covers.

LSP Bridge Architecture

The desktop LSP uses a Tauri native host + stdio JSON-RPC architecture, managing language server subprocesses, stdin writes, stdout reader threads, and message queues via src-tauri/src/lsp.rs.

Supported Language Families (15)

C# LSP Priority Chain

C# has a multi-layer fallback mechanism for LSP:

1. csharp-ls on system PATH or in ~/.dotnet/tools
2. Release package built-in csharp-ls binary (generated/lsp-tools/csharp-ls/bin/)
3. Built-in CodePapr.CSharp.Analyzer (custom Roslyn sidecar, supports cross-file and cross-ProjectReference resolution)
4. dotnet run --project CodePapr.CSharp.Analyzer.csproj (development / source code fallback)
5. omnisharp -lsp or OmniSharp -lsp on system PATH (static candidate only)
6. Built-in tree-sitter symbol parsing (final fallback)

Managed Installation (Managed LSP)

The desktop manages on-demand installation of missing LSP tools at runtime:

• Node-based (5 npm packages, providing 7 language services): typescript-language-server (TypeScript / JavaScript), vscode-langservers-extracted (HTML / CSS / JSON), yaml-language-server, pyright, bash-language-server — installed via npm using the built-in Node.js runtime v20.12.2
• Binary-based (6): clangd v22.1.6, rust-analyzer, JDTLS + Temurin JRE 21, sqls, marksman, gopls — downloaded from official sources
• C#: Installed via dotnet tool install -g csharp-ls, or uses the built-in Roslyn sidecar
• Auto managed downloads can be disabled with CODEPAPR_DISABLE_MANAGED_LSP_DOWNLOAD=1

Tree-sitter Syntax Parsing (16 Languages)

Built-in tree-sitter syntax tree parsing used for ProjectGraph and fallback symbol extraction: TypeScript, JavaScript, Python, Rust, Java, Go, C++, Bash, C#, CSS, HTML, JSON, PHP, Ruby, Kotlin, Swift.

LSP Loading Strategy

• No batch warm-up of LSP at workspace startup
• The LSP for a file is asynchronously loaded only after the file is displayed
• After generation/modification/save-to-disk, asynchronously refreshes diagnostics and symbol cache for the related file
• The LSP backend caches full workspace diagnostics; cross-file errors are also detectable
• The code area only shows hints when there are problems; stays clean when there are none
• When upper-layer LSP is unavailable, falls back to built-in tree-sitter symbol parsing

Verification Command Matrix

Recommended Pre-commit Regression Order

npm run build
npm run test
npm run test:e2e
npm run test:e2e:ui
npm run verify

Browser dependencies must be installed before the first UI E2E run:

npm run test:e2e:ui:install

Desktop Release

# Development debugging
npm run debug

# Optimized desktop runtime (no packaging)
npm run release

# Generate installer (.dmg / .msi) and organize into Release/
npm run publish

Release Helper Scripts

• macOS: ./publish-codepapr.command
• Windows: publish-codepapr.cmd

Pre-release Checks

npm run release:prep
npm run publish:dry-run

1. Understand First, Then Execute

Best when working with a repository for the first time or when requirements are unclear:

1. Ask: Explain system structure, locate modules
2. Plan: Output task checklist and verification plan
3. Agent: Execute according to the checklist

2. Direct Fix

Best when you already know the target but don't want to manually search and fix:

Fix the incorrect cache statistics in packages/@codepapr/api.
First locate the statistics aggregation logic, then make a minimal fix, and finally run related tests.

3. Start Frontend and Preview In-App

Best for UI adjustments, page behavior verification, and preview integration:

1. Let the Agent start a preview session or background command
2. View the page in the in-app preview
3. If you need to click pages, fill forms, or take screenshots, continue using browser tools

4. Persist Terminal Context for Sequential Operations

Best for scripts, REPL, interactive CLI, or multi-step shell workflows:

1. Open a shell session
2. Send commands continuously
3. Proceed based on output
4. Close the session when done

5. Review Historical Sessions and Costs

• View the session list
• View stats for a specific session (cache hits/misses/token usage)
• Assess whether costs are reasonable against the current model settings

DeepSeek Model Reference

How to Choose in CodePapr

• Primary model defaults to deepseek-v4-pro — used for Ask, Plan, Agent, and App main execution flow; App mode always uses the primary model for generation quality
• Fast model defaults to deepseek-flash — used for context compression, sub-task planning, read-only lightweight sub-agents
• Thinking effort (thinkingEffort) defaults to max (strongest reasoning); can be switched to high in the LLM settings tab

Cost Optimization Tips

• Prefer cheaper models for Ask and lightweight analysis tasks
• Use Plan before large changes to reduce ineffective execution rounds
• Make task descriptions more specific to reduce the number of rounds the model spends searching and fixing
• Keep system prompts and tool boundaries stable to maximize prefix cache hits

1. Prompt says no API key after startup

First check whether the desktop settings have been saved, and whether the corresponding environment variables are set (DEEPSEEK_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY).

2. Installation or npm scripts won't run / not found

Confirm whether npm install and npm run build have been executed, and whether the current repository is under a OneDrive path causing .bin shim anomalies.

3. Agent encounters vite, tsc, eslint, or missing module errors

First suspect uninstalled dependencies or unbuilt local packages, rather than cloud sync or disk issues.

4. Browser tool unavailable

Usually because no detectable Chrome or Chromium-compatible browser is installed on the machine.

5. Tests still show old results after code changes

Many packages in this repository participate in tests or references through their respective dist entry points. After changing source files, if results look unchanged, first rebuild the affected packages, then run verification.

6. Build principles after modifying source code

Important: Modify source → build first → run affected tests → run broader verification. When results appear "not taking effect," first suspect the build wasn't applied, rather than suspecting a runtime anomaly.

7. How to use local models

In settings, you can connect to a local model provider (OpenAI-compatible endpoint) for offline or private deployment scenarios. With supported models, you can paste or drag images directly into the chat box as input.

8. Why does a popup appear when reading certain absolute paths

This is the desktop's external path permission mechanism. When the Agent attempts to read or list absolute paths outside the project, it requests your explicit authorization to ensure system files are not accessed without permission.

9. UI E2E tests won't run

First confirm whether Playwright browser dependencies have been installed:

npm run test:e2e:ui:install

UI E2E uses Chromium running in a mock environment without Tauri webview; real model configuration is not required.

Usage Tips

Beginners: First use Ask to understand the system → then Plan to see the scope of changes clearly → finally use Agent for actual execution. Need data visualization? Switch to App mode and generate interactive charts in one sentence.

Experienced users: Give clear goals directly in Agent mode → specify affected files and verification requirements → use the desktop to complete conversation, Git, preview, and browser integration.