CodePapr Tutorial

What is CodePapr

CodePapr is a cache-first coding agent system offering two entry points: a Tauri desktop workbench and a CLI terminal interface. It shares a common Agent Runtime to provide desktop and terminal CLI with the same capabilities, enabling AI agents to read, modify, execute, verify, and preview within real project repositories.

CodePapr is neither a traditional AI chat tool nor an IDE plugin. It is an autonomous agent running in the terminal/desktop that genuinely understands your project context and automatically executes development tasks.

Core Design Principles

• Local-first: Project context stays within the workspace as much as possible; file and command execution happen locally
• Single Runtime, Multiple Entry Points: The desktop workbench and CLI terminal share the same Agent, Session, ToolRegistry, and Provider semantics
• DeepSeek Cache Optimization: Stable content upfront, volatile content at the end, maximizing prefix cache hit rates to reduce token costs
• Structured Code Editing: Uses Search/Replace Diff mechanism, validates before writing, avoids line-number drift
• Verifiable Execution Chain: Every round of request, response, tool call, and cache statistics is traceable

CodePapr vs. Mainstream AI Coding Tools

By 2026, AI coding tools are already very mature. The comparison below is based on each tool's current public capabilities, presented truthfully.

Who Should Use CodePapr

• You have mastered at least one programming language and can read basic syntax and project structure
• Engineers looking to dramatically boost development efficiency with AI
• Independent developers or tech leads maintaining complex projects long-term
• Developers comfortable switching between command line and visual interfaces
• Teams concerned about token costs who want to leverage DeepSeek cache optimization to reduce expenses

Prerequisites

• Basic programming skills (can read and write simple code)
• Basic code reading and comprehension ability
• Familiarity with common dev tools (editor, command line, Git)
• Basic understanding of project structure (directories, module organization)
• Willingness to understand code rather than fully relying on AI

Supported LLM Providers

Requirements

Standard Installation

# After cloning the repository
npm install
npm run build

Installation Verification

npm run verify

Passing this step confirms that your machine at least satisfies: correct Node dependencies, successful workspace build, passing workspace tests, passing CLI E2E 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 and CLI 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. Prepare configuration: Fill in your API key, provider, and model in the desktop settings
2. Choose entry point: Use the desktop workbench directly (the current public product entry only exposes the desktop workbench)
3. Choose mode: Ask for explanation and analysis, Plan for breaking down solutions, Agent for actual execution

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, and Agent
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 CLI includes two built-in sub-agents: Explore and Scout; Mentor is only available and configurable in the desktop's "Sub-agents" tab.

Ask, Plan, and Agent are not different products but three 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:

• Does not modify files or run commands by default
• 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, seeing affected files and verification paths, breaking complex tasks into clear steps.

Characteristics:

• Provides a task checklist by default
• Shows affected files, execution order, verification methods, and risks
• Best for planning first, then switching to Agent for execution

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, background commands, shell, 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 exec 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

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

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
• Auto-init: If the current workspace is not yet a Git repository, the panel can directly execute git init

Conversation Reset (Git Checkpoint)

Before each user message enters the conversation history, CodePapr captures a code snapshot as an anchor:

git add -A && git commit -m "codepapr:checkpoint:<userMsgId>"

When you need to roll back:

• Hover over any user message and click "Reset to here"
• The system git reset --hard to the checkpoint commit before that message was sent
• All files are atomically restored to the state before sending that message
• The message list is synchronously truncated; all subsequent conversation is removed
• If the workspace is not a Git repository, CodePapr will first attempt git init; if initialization fails, the "Reset to here" button on that message remains disabled

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

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; the CLI's read boundaries are more lenient, while writes remain restricted to the workspace.

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.

CodePapr supports creating, importing, and managing AI characters, allowing the Agent to converse with you in a specific persona. Once a character is activated, their identity, tone, and style are injected into the LLM system prompt, and the Agent responds in that character's persona.

Character Data Model

Each character includes the following fields:

Roleplay Format Conventions

When a character is activated, the system prompt specifies the following format rules to ensure TTS can correctly distinguish dialogue from actions:

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.

Activating/Switching Characters

Click a character name in the character list to activate it. The currently active character will display an "Active" marker. Every Agent response will be delivered in that character's persona.

Character personas are placed in the Session Bootstrap (not in the system prompt's ImmutablePrefix), so switching characters does not break the DeepSeek prefix cache.

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 and enable "Enable Voice Output"
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
7. Click the "Preview" button to preview the effect
8. Click Save when satisfied

Current Playback Mode

The current UI uses WebSocket batch streaming (ws-batch) as the default and only effective mode: all sentences are sent in bulk 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 code layer retains three modes: whole, streamed-pipeline, and streamed-pcm, but the character editing panel has not yet exposed a switch for them; users need not worry about this.

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

.CodePapr/memory.md — Cross-Session Project Memory (Auto-Organized)

During work, the Agent automatically discovers project-specific patterns, pitfalls, and conventions and writes them into the memory file. Automatically loaded at the start of the next session, helping the Agent avoid repeating past mistakes. The file is automatically reorganized when it exceeds 200 lines to prevent unbounded growth.

• Auto-accumulation: When the Agent discovers project-specific knowledge, it uses write to append to .CodePapr/memory.md, with each entry prefixed by ## YYYY-MM-DD Topic
• Auto-loading: Injected into bootstrap context at the start of each session, without affecting system prompt cache
• Auto-organization: At session start, if memory.md > 200 lines, or context compression / /compact triggers a pending flag; after the current round's Agent reply completes, the fast model asynchronously deduplicates, merges, and condenses the memory, then writes it back to the file
• Non-blocking: Organization is fire-and-forget async; the current session uses old memory, the next session uses the organized version; on failure, silently degrades to rule-based dedup without affecting the main flow
• No new tools: Organization is triggered by store-layer background logic, invisible to the model, not breaking ImmutablePrefix cache
• Recording principles: User preferences, project conventions, error patterns and solutions, architectural decisions; do not record general programming knowledge, temporary task states, or rules already in .CodePapr/AGENTS.md

/compact — Force Context Compression

Manually trigger conversation compression, merging earlier messages into structured checkpoints to free token space:

• Force mode: Not limited by maxConversationRounds and maxContextTokens thresholds
• Local command: Zero token cost; calls the existing compression pipeline to generate checkpoints
• Incidentally triggers memory organization: After successful compression, marks memory.md as pending; next round's agent reply triggers async organization
• 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).

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)
• 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

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

---
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`

Template Syntax

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 25 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

Rust Backend Domain Modules

The Tauri backend is split into multiple modules by responsibility:

• browser: Headless Chromium browser automation
• shell: Foreground/background commands, persistent shell sessions, command safety guards
• web: HTTP fetch, web page extraction, multi-engine search
• workspace_fs: File listing, reading, writing, SEARCH/REPLACE diff, searching
• task_queue: Heavy I/O operation serialization queue
• db: App and project-level SQLite persistence
• lsp: LSP server process management
• symbol_provider: Tree-sitter fallback symbol extraction
• mcp_host: MCP tool server host
• shared: Path normalization, workspace path resolution, general utilities

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

Three-Layer Prompt Injection

The system injects prompts in three layers, ordered from most to least stable to maximize DeepSeek automatic prefix cache hits:

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

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, and Agent main execution flow
• Fast model defaults to deepseek-v4-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 CLI commands 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.

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.