# Auto Compact
URL: /auto-compact
Reduce context usage by summarizing long conversations—inline or into a new task
***

title: "Auto Compact"
description: "Reduce context usage by summarizing long conversations—inline or into a new task"
icon: "ScanText"
----------------

# Auto Compact

Auto Compact helps you keep long conversations efficient by summarizing earlier messages when your token usage grows large. You can either:

* Compact in the current task (inject a compact summary so you can continue seamlessly)
* Start a new task with the summary (spawn a fresh task seeded with a concise recap)

![Auto Compact overview](../assets/images/auto-compact.png)

## When Auto Compact is available

Auto Compact becomes available from the token usage chip in the toolbar when all of the following are true:

* The conversation isn’t streaming or executing
* The chat isn’t read-only
* No other compact action is pending
* Total tokens ≥ 50,000 (min threshold)

If the threshold isn’t met, you’ll see a tooltip explaining that more tokens are required to compact.

While compacting, the chip shows a spinner with the “Compacting” label.

![Compacting in progress](../assets/images/auto-compacting.png)

## Two ways to compact

### Option A — Compact in current task

Use this to stay in the same task. Pochi will:

1. Generate a concise summary of the conversation up to your latest message
2. Inject a compact block at the top of your last user message
3. Continue the conversation with the condensed context

> Notes: The summary is wrapped into a compact section and prepended to your last message to preserve intent while saving context.

### Option B — Start new task with summary

Use this to branch a fresh task based on the current work. Pochi will:

1. Create a summary of the existing conversation
2. Open a new task seeded with the summary and a short handoff message
3. Navigate you to the new task to continue

![Inline compact summary in current task (expandable)](../assets/images/auto-compact-with-new-task-summery.png)

## Technical Details

* Trigger: You choose either “Compact task” (inline) or “New task with summary”.
* Summary prompt: Pochi asks the model to produce a concise recap focused on key topics, decisions, and important context (limited to a few thousand tokens of output).
* Inline compact: The recap is wrapped in a compact block and prepended to your last user message before the next response.
* New task: The recap becomes the first message of a brand-new task, followed by a short instruction letting the agent analyze status and confirm next steps.
* Safety/availability: Buttons are disabled during streaming/execution, or when below the minimum token threshold.

## Tips

* Prefer inline compact when you want continuity within the same task.
* Use “new task with summary” to cleanly branch, hand over, or checkpoint work.
* You’ll see a “Compacting” state while the summary is being generated—this can take a moment for very long threads.


# Checkpoints
URL: /checkpoint

***

title: Checkpoints
icon: "Route"
-------------

# Checkpoints

Checkpoints automatically save a snapshot of your workspace after key steps in a task. They help you track changes, roll back when needed, and explore different implementations without worrying about breaking your code.

<div align="center">
  ![Checkpoint overview](../assets/images/checkpoint-overview.png)
</div>

## How checkpoints work

Pochi creates a checkpoint after important actions such as file edits or applied fixes. These checkpoints:

* Run alongside your Git workflow without interference
* Preserve the conversation context when restoring (chat and task context remain intact)
* Track file changes using a shadow Git repository (no writes to your real repository)

Example: while developing a feature, the assistant updates multiple files. Each change creates a checkpoint. You can review each modification, and if needed, roll back to any point without impacting your main branch or real Git history.

## Viewing changes and restoring

After each key action, you can:

1. Click Compare to see modified files and diffs
2. Click Restore to open restore options

<div align="center">
  ![Checkpoint compare](../assets/images/checkpoint-compare.png)
</div>

## Restore options

To go back to a previous point:

1. Click Restore next to any step
2. Choose how you want to restore:
   * Restore Workspace and Task (when available): revert both code and task context
   * Restore Task Only (when available): keep code changes, revert task context
   * Restore Workspace Only: revert code while preserving task context (current default)

Note: The current version focuses on “Restore Workspace Only.” Other options will appear as their capabilities are enabled.

<div align="center">
  ![Checkpoint restore options](../assets/images/checkpoints-restore.png)
</div>

## Under the hood

In VS Code, Pochi implements checkpoints with a shadow Git that stays separate from your real repository:

* Initializes a bare repository under the extension’s storage directory (scoped per workspace)
* Points the worktree to your workspace, then stages and commits changes into the shadow repo
* Excludes common large/binary/cache/build artifacts (see Exclusions) to keep things fast and stable

This shadow repo is fully independent. Saving or restoring checkpoints does not create commits in your actual Git repository.

## Requirements

* **Git** must be installed (the shadow Git depends on it). If Git isn’t available, the checkpoint feature can’t initialize and will be disabled.

## Smart detection and exclusions

Pochi automatically detects and excludes heavy or redundant files to keep checkpoints lean and fast, including:

* Build artifacts and dependency folders
* Media files and large binaries
* Cache, logs, and temporary files
* Environment configuration files
* Files tracked by Git LFS

With this smart filtering, checkpoints focus on core code changes—making diffs clearer and restores faster.


# CLI
URL: /cli
Pochi CLI allows you to run an AI agent directly from the command line.
***

title: CLI
description: Pochi CLI allows you to run an AI agent directly from the command line.
icon: "SquareTerminal"
----------------------

# CLI

Pochi offers a command-line interface (CLI) that allows you to run an AI agent directly from the command line.

## Oneliner Install

<Tabs items={['Curl', 'Homebrew', 'NPM']}>
  <Tab value="Curl">
    ```bash
    curl -fsSL https://getpochi.com/install.sh | bash
    ```

    To install a specific version, pass the version tag as an argument. For example:

    ```bash
    curl -fsSL https://getpochi.com/install.sh | bash -s "pochi-v0.5.5"
    ```
  </Tab>

  <Tab value="Homebrew">
    ```bash
    brew install tabbyml/pochi/pochi
    ```
  </Tab>

  <Tab value="NPM">
    ```bash
    npm install -g @getpochi/cli
    ```
  </Tab>
</Tabs>

## Authentication

The Pochi CLI uses the same authentication credentials as the VS Code extension for Pochi's cloud services. When you sign in through the VS Code extension, the CLI automatically reuses these credentials.

Credentials are stored in `~/.pochi/config.jsonc`. To authenticate:

1. Install and open the [Pochi VS Code extension](https://marketplace.visualstudio.com/items?itemName=TabbyML.pochi)
2. Follow the sign-in prompts in the extension
3. The CLI will automatically use the same credentials

For non-Pochi models, first configure it in your Pochi configuration file (`~/.pochi/config.jsonc`). See [Models documentation](./models.mdx) for details on how to configure custom providers.

Then you can use the model by specifying the provider and model ID separated by a slash:

```bash
pochi --model groq/llama3-8b-8192 -p "What is the time now?"
```

## Usage

You can pass a prompt to run a task:

```bash
pochi -p "What is the time now?"
```

Or pipe input as a prompt:

```bash
echo "What is the time now?" | pochi
```

For detailed usage instructions, run `pochi -h`, below is the output fom version 0.5.3

```
Usage: pochi [options]

Pochi v0.5.5

Prompt:
  -p, --prompt <prompt>   Create a new task with the given prompt. You can also
                          pipe input to use as a prompt, for example: `cat
                          prompt.txt | pochi`.

Options:
  --max-steps <number>    Maximum number of stepsto run the task. If the task
                          cannot be completed in this number of rounds, the
                          runner will stop. (default: 24)
  --max-retries <number>  Maximum number of retries to run the task in a single
                          step. (default: 3)

Model:
  --model <model>         The model to use for the task. (default:
                          "qwen/qwen3-coder")

Others:
  -V, --version           Print the version string.
  -h, --help              Print this help message.
```

## Debugging

To enable debug logging for the CLI, you can set the `POCHI_LOG` environment variable:

```bash
POCHI_LOG=debug pochi -p "What is the time now?"
```

This will output detailed logs about the CLI's operation, which can be helpful for troubleshooting issues.

For more granular control, you can specify log levels for specific components:

```bash
POCHI_LOG=Pochi=debug,TaskRunner=trace pochi -p "What is the time now?"
```


# Custom Agent
URL: /custom-agent
Learn how to create and use custom agents in Pochi.
***

title: Custom Agent
icon: Bot
description: Learn how to create and use custom agents in Pochi.
----------------------------------------------------------------

# Custom Agents

Pochi allows you to define custom agents to handle specific tasks. These agents can be tailored with their own system prompts and sets of tools, enabling you to create specialized assistants for your workflows.

## Defining a Custom Agent

Custom agents are defined in `.md` files located in either the project's `.pochi/agents/` directory or the system-wide `~/.pochi/agents/` directory.

An agent definition file consists of two parts: a frontmatter section for configuration and a content section for the system prompt.

Here is an example of a custom agent definition:

```markdown
---
description: Description of when this custom agent should be invoked
tools:
  - tool-1
  - tool-2
  - tool-3
---

Your custom agent's system prompt goes here. This can be multiple paragraphs
and should clearly define the custom agent's role, capabilities, and approach
to solving problems.

Include specific instructions, best practices, and any constraints
the custom agent should follow.
```

If the agent is saved as `my-agent.md` and the `name` attribute is omitted, `my-agent` will be used as the agent name.

### Configuration

The frontmatter provides metadata for the custom agent:

* `name` (optional): A unique name for your agent. If omitted, the filename (without the extension) is used as the name.
* `description` (required): A short description of what the agent does. This is used to help Pochi decide when to use your agent.
* `tools` (optional): A list of tools that the agent is allowed to use. This can be a comma-separated string (e.g., `tool-1, tool-2`) or a YAML array. If omitted, the agent inherits all available tools.

### Tool-specific rules

Rule entries follow the format `tool` or `tool(specifier)`. The following tools support specifier-based restrictions:

* `executeCommand`, `startBackgroundJob` — Command patterns, e.g. `executeCommand(npm run *)`, `startBackgroundJob(npm run dev)`
* `readFile`, `writeToFile`, `applyDiff`, `editNotebook` — Path globs, e.g. `readFile(src/**)`
* `webFetch` — Domain patterns, e.g. `webFetch(domain:*.example.com)`

A tool declared without parentheses (e.g., `readFile`) has no restrictions. Use one declaration per rule — commas inside a specifier are not supported; add separate entries for multiple rules.

#### Command Execution Restrictions

Restrict which shell commands the agent can run via `executeCommand`. The specifier is matched against each individual command segment (split on `;`, `&&`, `||`, `|`). If any segment does not match at least one allowed pattern, the tool call is rejected.

| Declaration                      | Behavior                                                      |
| -------------------------------- | ------------------------------------------------------------- |
| `executeCommand`                 | No restrictions — allows any command                          |
| `executeCommand(npm)`            | Allows commands whose first token is `npm`                    |
| `executeCommand(npm *)`          | Allows command segments matching the pattern `npm *`          |
| `executeCommand(npm run test)`   | Allows command segments matching exactly `npm run test`       |
| `executeCommand(npm run test *)` | Allows command segments matching the pattern `npm run test *` |

#### Background Job Restrictions

Restrict which long-running commands the agent can launch via `startBackgroundJob`. The same command-pattern matching used for `executeCommand` applies here, but the two policies are independent — an `executeCommand(...)` rule does **not** authorize a `startBackgroundJob` call, and vice versa. Declare separate entries for each tool as needed.

| Declaration                         | Behavior                                                        |
| ----------------------------------- | --------------------------------------------------------------- |
| `startBackgroundJob`                | No restrictions — allows any background command                 |
| `startBackgroundJob(npm)`           | Allows background commands whose first token is `npm`           |
| `startBackgroundJob(npm *)`         | Allows background commands matching the pattern `npm *`         |
| `startBackgroundJob(npm run dev)`   | Allows starting only `npm run dev` as a background job          |
| `startBackgroundJob(npm run dev *)` | Allows background commands matching the pattern `npm run dev *` |

#### Path-based File Restrictions

Restrict which files the agent can read or modify using workspace-relative glob patterns. Applies to `readFile`, `writeToFile`, `applyDiff`, and `editNotebook`. Access to any path outside the specified patterns is rejected.

| Declaration                  | Behavior                                         |
| ---------------------------- | ------------------------------------------------ |
| `readFile`                   | No restrictions — allows reading any file        |
| `readFile(src/**)`           | Allows reading all files under `src/`            |
| `readFile(packages/**/*.md)` | Allows reading markdown files under `packages/`  |
| `writeToFile(.pochi/**)`     | Allows writing only to files under `.pochi/`     |
| `writeToFile(logs/*.log)`    | Allows writing only to log files under `logs/`   |
| `applyDiff(src/**)`          | Allows applying diffs only to files under `src/` |
| `editNotebook(docs/*.ipynb)` | Allows editing only notebook files under `docs/` |

#### Domain-based Web Restrictions

Restrict which domains the agent can fetch via `webFetch`. The specifier must start with `domain:`. URLs whose hostname does not match any allowed pattern are rejected.

| Declaration                      | Behavior                                                                           |
| -------------------------------- | ---------------------------------------------------------------------------------- |
| `webFetch`                       | No restrictions — allows fetching any URL                                          |
| `webFetch(domain:example.com)`   | Exact domain match (e.g., allows only `example.com`)                               |
| `webFetch(domain:*.example.com)` | Glob match against subdomains (e.g., allows `api.example.com`, `docs.example.com`) |

#### New Task Restrictions

Restrict which agent types a custom agent can launch using `newTask`.

* `newTask(_)` allows launching only the default agent (when `agentType` is omitted).
* `newTask(browser)` allows launching only the `browser` agent.
* `newTask(explorer-*)` allows launching any agent whose name starts with `explorer-`.

Example:

```markdown
---
description: Code reviewer with restricted filesystem and network access
tools:
  - executeCommand(git diff)
  - executeCommand(grep *)
  - startBackgroundJob(npm run dev)
  - readFile(src/**)
  - readFile(packages/**/*.md)
  - writeToFile(.pochi/**)
  - webFetch(domain:docs.example.com)
  - webFetch(domain:*.getpochi.com)
  - newTask(_)
  - newTask(browser)
---
```

### System Prompt

The content of the file after the frontmatter is the system prompt for the agent. This prompt should define the agent's role, capabilities, and how it should behave.

## Using a Custom Agent

You can mention the custom agent's name in your prompt, and Pochi may decide to use it based on the context.

## Managing Custom Agents

You can manage your custom agents through the Pochi interface or by directly manipulating the agent definition files. The common operations include:

* **List**: View all available agents in the `.pochi/agents/` directory or in Pochi settings.
* **Create**: Create a new `.md` file in the `.pochi/agents/` directory.
* **Delete**: Remove the corresponding agent file.
* **Edit**: Modify the agent's definition file.


# Edits
URL: /edits
Send your local changes as additional context to Pochi
***

title: Edits
description: Send your local changes as additional context to Pochi
icon: "PencilLine"
------------------

# Edits

Edits account for changes you make locally while iterating on the code. If you fix something yourself, tweak a variable, or partially rewrite a block before asking for help, Pochi captures those recent edits and includes them as part of the review context.

Instead of only seeing the final file state, the agent receives the exact diffs you introduced, which helps it reason about what changed, where it changed, and what you were likely trying to adjust.

This gives the agent a clearer signal of your current intent and what should be addressed next.

<video
  controls
  style={{
      width: "100%",
      borderRadius: "8px",
      boxShadow: "0 4px 12px rgba(0, 0, 0, 0.15)",
      }}
>
  <source src="https://assets.docs.getpochi.com/useredits.mp4" type="video/mp4" />

  Your browser does not support the video tag.
</video>

## How to Use Edits

### 1. Make your changes

You can open the diff from the last response and make direct changes to the written code.

![Pochi Models](../assets/images/edits-creation-process.png)

All local changes you make gets reflected in the chatbox UI.

![Pochi Models](../assets/images/edits-tracking-prompt-ui.png)

### 2. Send Edits as a Batch

Once you’re done making changes, submit your next prompt as usual.

For example:

```bash
Please review the edits
```

or with extra guidance:

```bash
Use these edits to understand the new functions we need to add
```

Pochi will include your recent edits together with your message and use them as structured context for the next step.

![Pochi Models](../assets/images/edits-submitted-prompt.png)

This lets the agent build directly on top of what you already adjusted, without you needing to re-explain those changes in chat.


# Getting Started
URL: /
Welcome to Pochi - Full-Stack AI Teammate Guide
***

title: "Getting Started"
description: "Welcome to Pochi - Full-Stack AI Teammate Guide"
icon: "Album"
-------------

# Getting Started

[Pochi](https://getpochi.com) is an open-source AI coding agent built as a VS Code extension, checkout the video below to see it in action.

<div
  style={{
  position: "relative",
  paddingBottom: "53.7%",
  marginBottom: 20,
  height: 0,
  overflow: "hidden",
  maxWidth: "100%",
}}
>
  <iframe
    src="https://drive.google.com/file/d/1CDxAcO9WGFFC45x5a5HDFdT4u6rtdJrB/preview"
    style={{
    position: "absolute",
    top: 0,
    left: 0,
    width: "100%",
    height: "100%",
    border: "none",
    borderRadius: "8px",
  }}
    allowFullScreen
    title="Pochi Demo - End-to-End Experience"
  />
</div>

## Installation

Install the Pochi extension from the [VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=TabbyML.pochi) or [OpenVSX](https://open-vsx.org/extension/TabbyML/pochi).

We recommend dragging Pochi to the right side of your VSCode window to get the best experience.

![Drag to right sidebar](../assets/images/vscode-right-sidebar.png)

With Pochi, you can use any LLM provider by configuring their API keys. Use the VS Code command `Pochi: Open Custom Model Settings` to open the settings file and [configure it](./models). Alternatively, Pochi offers cloud-based services. Creating a Pochi account gives you access to:

* Pochi's managed LLM models
* Shared task histories and team management

To use these features, sign up at [app.getpochi.com](http://app.getpochi.com) and log in to your VS Code extension.

## Customize

Pochi supports hierarchical configuration with both global (user-level) and workspace-specific settings.

1. **Global Configuration**: `~/.pochi/config.jsonc` - Your default configuration available across all projects
2. **Workspace Configuration**: `.pochi/config.jsonc` - Project-specific configuration that override or extend global settings

You can tailor Pochi to your needs by editing these configuration file. The file uses the JSONC (JSON with Comments) format, so you can add notes to explain your settings.

```jsonc
{
  // The schema enables autocompletion and validation in your code editor.
  "$schema": "https://getpochi.com/config.schema.json",

  // For details on available options, see the "Models," "Rules," pages in the sidebar
  // ...
}
```


# MCP
URL: /mcp
Model Context Protocol integration and configuration
***

title: MCP
description: Model Context Protocol integration and configuration
icon: "Spline"
--------------

# MCP (Model Context Protocol)

The **Model Context Protocol (MCP)** revolutionizes how Pochi interacts with external services, databases, and APIs. Think of MCP as a universal adapter that connects Pochi to virtually any data source or tool, dramatically expanding what your AI assistant can accomplish.

## Configure

Use the VSCode command `Pochi: Open MCP Server Settings` to open the settings.

```json
{
  "mcp": {
    "context7": {
      "command": "npx",
      "args": ["@upstash/context7-mcp"]
    }
  }
}
```

After saving the configuration, you will see the MCP server appear in the **Tools** section of Pochi's settings page.

![MCP Server Context7](../assets/images/mcp-context7.png)

You can use the toggle switch to enable or disable the MCP server entirely. You can also click on the tool badge to toggle individual tools within the MCP server.

## Examples

### Local MCP Servers (Stdio Transport)

```json
{
  "filesystem": {
    "command": "npx",
    "args": [
      "-y",
      "@modelcontextprotocol/server-filesystem",
      "/path/to/allowed/files"
    ],
    "env": {
      "HOME": "/Users/yourname"
    }
  }
}
```

### Remote MCP Servers (HTTP Transport)

#### Custom API Server

```json
{
  "my-api": {
    "url": "https://api.mycompany.com/mcp",
    "headers": {
      "Authorization": "Bearer your-api-token",
      "X-API-Version": "v1"
    }
  }
}
```

#### SSE (Server-Sent Events) Server

```json
{
  "realtime-data": {
    "url": "https://data.example.com/mcp/sse",
    "headers": {
      "Authorization": "Bearer your-token"
    }
  }
}
```

## Configuration Hierarchy

Pochi supports hierarchical MCP configuration with both global (user-level) and workspace-specific settings.

1. **Global Configuration**: `~/.pochi/config.jsonc` - Your default MCP servers available across all projects
2. **Workspace Configuration**: `.pochi/config.jsonc` - Project-specific MCP servers that override or extend global settings

The workspace configuration takes precedence and is merged with the global configuration, allowing you to:

* Add project-specific MCP servers
* Override global server configurations for specific projects
* Maintain different MCP setups for different codebases

### Global MCP Configuration Example (`~/.pochi/config.jsonc`)

```json
{
  "mcp": {
    "context7": {
      "command": "npx",
      "args": ["@upstash/context7-mcp"]
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/Documents"
      ]
    }
  }
}
```

### Workspace MCP Configuration Example (`.pochi/config.jsonc`)

```json
{
  "mcp": {
    "project-db": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-sqlite", "./database.db"]
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "./src"
      ]
    }
  }
}
```

In this example:

* The `context7` server from global config will be available
* The workspace-specific `project-db` server will be added
* The `filesystem` server configuration will be overridden to only access the project's `src` directory


# Models
URL: /models
Manage Pochi's model settings
***

title: Models
description: Manage Pochi's model settings
icon: "Zap"
-----------

# Models

Pochi leverages the AI SDK to support various LLM providers and can run local models.

## Pochi

After signing in, you gain access to the Pochi models shown below. Pochi uses a usage-based pricing strategy with no additional charges. For detailed pricing information, visit [https://app.getpochi.com/pricing](https://app.getpochi.com/pricing).

![Pochi Models](../assets/images/pochi-models.png)

## OpenAI Compatible

Pochi allows you to configure any LLM provider that offers an OpenAI-compatible API by setting up the appropriate API keys. To configure custom models, use the VS Code command `Pochi: Open Custom Model Settings` to open the settings configuration file.

```json
{
  "$schema": "https://getpochi.com/config.schema.json",
  "providers": {
    "provider-id": {
      "apiKey": "your_api_key",
      "baseURL": "https://api.provider.com/v1",
      "models": {
        "model-id": {
          // The contextWindow and maxTokens are optional right now, it's default set to 10k and 4096
          // "contextWindow": 131072,
          // "maxTokens": 8000
        }
      }
    }
  }
}
```

### Chutes

Chutes provides access to various AI models through their API. To use Chutes, you'll need to obtain an API token from [Chutes Platform](https://chutes.ai/).

```json
{
  "$schema": "https://getpochi.com/config.schema.json",
  "providers": {
    "chutes": {
      "apiKey": "your_api_token",
      "baseURL": "https://llm.chutes.ai/v1",
      "models": {
        "zai-org/GLM-4.5-FP8": {
          "name": "glm-4.5"
        }
      }
    }
  }
}
```

### Cerebras

Cerebras provides AI models through their OpenAI-compatible API. To use Cerebras, you'll need to obtain an API key from [Cerebras Platform](https://inference.cerebras.ai/).

```json
{
  "$schema": "https://getpochi.com/config.schema.json",
  "providers": {
    "cerebras": {
      "apiKey": "your_api_key",
      "baseURL": "https://api.cerebras.ai/v1",
      "models": {
        "llama3.1-8b": {
          "name": "llama-3.1-8b"
        }
      }
    }
  }
}
```

### DeepInfra

DeepInfra provides access to a wide range of AI models through their OpenAI-compatible API. To use DeepInfra, you'll need to obtain an API token from [DeepInfra Platform](https://deepinfra.com/).

```json
{
  "$schema": "https://getpochi.com/config.schema.json",
  "providers": {
    "deepinfra": {
      "apiKey": "your_api_token",
      "baseURL": "https://api.deepinfra.com/v1/openai",
      "models": {
        "meta-llama/Llama-3.3-70B-Instruct": {
          "name": "llama-3.3-70b"
        }
      }
    }
  }
}
```

### Groq

Groq is a cloud-based AI platform that provides fast inference for large language models.

```json
{
  "$schema": "https://getpochi.com/config.schema.json",
  "providers": {
    "groq": {
      "apiKey": "your_api_key",
      "baseURL": "https://api.groq.com/openai/v1",
      "models": {
        "llama3-8b-8192": {
          "name": "llama-3-8b"
        }
      }
    }
  }
}
```

### LM Studio

LM Studio is a local IDE application that allows you to run and experiment with language models on your own machine.

```json
{
  "$schema": "https://getpochi.com/config.schema.json",
  "providers": {
    "lmstudio": {
      "baseURL": "http://127.0.0.1:1234/v1",
      "models": {
        "gemma-2b-it-q4f32_1": {
          "name": "gemma-2b"
        }
      }
    }
  }
}
```

### Mistral

Mistral AI provides a range of powerful language models available through their API. To use Mistral models, you'll need to obtain an API key from [Mistral AI Platform](https://console.mistral.ai/).

```json
{
  "$schema": "https://getpochi.com/config.schema.json",
  "providers": {
    "mistral": {
      "apiKey": "your_api_key",
      "baseURL": "https://api.mistral.ai/v1",
      "models": {
        "mistral-small-latest": {
          "name": "mistral-small"
        }
      }
    }
  }
}
```

### Ollama

Ollama is a tool that allows you to run large language models locally on your machine with a simple API.

```json
{
  "$schema": "https://getpochi.com/config.schema.json",
  "providers": {
    "ollama": {
      "baseURL": "http://localhost:11434/v1",
      "models": {
        "llama3:8b": {
          "name": "llama-3-8b"
        }
      }
    }
  }
}
```


# Parallel Agents
URL: /parallel-agents
Run multiple AI agents concurrently to accelerate development and tackle complex tasks.
***

title: "Parallel Agents"
description: "Run multiple AI agents concurrently to accelerate development and tackle complex tasks."
icon: "GitMerge"
----------------

# Parallel Agents

Most coding assistants can handle one task at a time. But real projects often need multiple agents exploring, refactoring, and developing different features in parallel - across different branches or experiments.
That's why we built **Parallel Agents**.

**Parallel Agents** let you run multiple Pochi agents concurrently, each inside its own Git worktree - isolated but synchronized with the same repository.
Each agent can explore the code base, develop different PRs, or test different ideas in parallel without interfering with each other, while you can check their works and manage them in Pochi extensions.

Pochi Parallel Agents has the following features:

* **Worktree Integration:** Leverage the Git worktree feature to gain an isolated env, did not recreate the wheel again.
* **Multi-to-Multi Execution:**  Tasks from Pochi could run in different worktree or the same one.
* **Task Management:** All tasks can be managed on the Pochi sidebar.
* **Integrated UX:** Review agents' works and open the terminal from one click.
* **VSCode Native:** Create new Agents directly from the Repository manage view from VSCode.

## Demo and Real World Use Cases

Let's go through the features of **Parallel Agents** by showing the real world workflow while we are developing Pochi.
For the following demo, we will work on those two issues:

1. [https://github.com/TabbyML/pochi/issues/619](https://github.com/TabbyML/pochi/issues/619)
2. [https://github.com/TabbyML/pochi/issues/654](https://github.com/TabbyML/pochi/issues/654)

Meanwhile, we'll explore together how worktree feature is implemented.

We could operate on the default worktree directly; however, since those two issues are independent, we prefer to create a separate worktree for each.

### Creating Worktree

There are multiple ways to create a new Worktree,

1. Create from Pochi sidebar directly

<div
  style={{
  position: "relative",
  paddingBottom: "53.7%",
  height: 0,
  overflow: "hidden",
  maxWidth: "100%",
}}
>
  <iframe
    src="https://drive.google.com/file/d/1HgO1JdMswvFOKhSwRQCU3pFOIv2lKRbB/preview"
    style={{
    position: "absolute",
    top: 0,
    left: 0,
    width: "100%",
    height: "100%",
    border: "none",
    borderRadius: "8px",
  }}
    allowFullScreen
    title="Create Pochi Tasks"
  />
</div>

2. Create from VSCode Repository management
   You can first create a new worktree in VSCode Source Control Panel. Then manually link this worktree to a branch, and open this worktree in Pochi.

<div align="center">
  ![Create Worktree](../assets/images/create-worktree.png)
</div>

<div align="center">
  ![Open Worktree in Pochi](../assets/images/worktree-pochi.png)
</div>

3. Let Pochi create a worktree for a new coding task\
   When you are submitting the message to create a new task, using `Cmd/Ctrl + Enter`, then Pochi will create a worktree for the new task. The worktree/branch name is generated according to the coding task.

In all cases, Pochi will create and check out the branch at the specified disk path as a worktree. You can then perform any action as if it were a standard Git repository, as an independent dev environment in each worktree.

### Create Task in Pochi

Now we are ready to initiate tasks in each worktree to let them run in parallel. You'd see that once a task is initiated, Pochi opens a new tab for each task, and you can switch between different tabs to monitor the progress of each task.

<div align="center">
  ![Parallel Tasks](../assets/images/parallel-tasks.png)
</div>

### Interaction with Tasks

When you click on the task, Pochi will open the specific task, allowing you to interact with it.

<div align="center">
  ![Interact with Tasks](../assets/images/task-interaction.png)
</div>

For instance, the task `fix-issue-654` is now complete. We can review the modifications by selecting `Diff worktree with origin/main`, and Pochi will open a tab showing all the files changes.

Or choose `Open in Integrated Terminal` to launch the terminal within this worktree for command execution.


# Permissions
URL: /permissions
Manage Pochi's auto-approval settings
***

title: Permissions
description: Manage Pochi's auto-approval settings
icon: "Shield"
--------------

# Permissions

By default, all permissions in Pochi are enabled. You can customize these permissions at any time using the Auto-Approve settings.

<div align="center">
  ![Auto Approve](../assets/images/auto-approve.png)
</div>

* **Read**: Read the file content Pochi decides to look up for analyzing or completing tasks.
* **Write**: Creates new files, edits existing code, generates boilerplate, and writes documentation.
* **Execute**: Manages dependencies, runs builds, tests, and perform system operations.
* **Use MCP**: Interacts with databases, APIs, and other external services to expand its capabilities with MCP server.
* **Retry**: Automatically retries failed commands, code changes, and installations.


# Queued Messages
URL: /queued-messages
Add tasks to a queue while Pochi is busy, ensuring a non-blocking experience.
***

title: Queued Messages
description: Add tasks to a queue while Pochi is busy, ensuring a non-blocking experience.
icon: "Layers"
--------------

# Queued Messages

The Queued Messages feature allows you to add multiple messages to a queue, which are then combined into a single prompt for execution. This lets you build up a complex request in pieces, which is especially useful while Pochi is busy.

<div align="center">
  ![Queued Messages UI](../assets/images/queued-messages.png)
</div>

When Pochi is busy, you don't have to wait to give it your next instruction. Here’s what happens:

1. **Queue with a Shortcut**: Type your prompt and press `Cmd+Enter` (`Ctrl+Enter` on Windows/Linux). Your message will be added directly to the queue.
2. **See What's in Line**: The "Queued Messages" panel appears, showing you a list of all the tasks waiting to be executed.
3. **Combined for Execution**: Once Pochi is ready, it will take all the messages from the queue, merge them into a single prompt, and then execute it.
4. **Remove with a Click**: If you decide you don't need a task done anymore, just click the `X` next to it to remove it from the queue.


# Reviews
URL: /reviews
Add, view, and manage line-level comments directly on the diff code
***

title: Reviews
description: Add, view, and manage line-level comments directly on the diff code
icon: "MessageCircleCode"
-------------------------

# Reviews

Reviews let you leave inline comments directly on the code generated by Pochi inside VS Code. Instead of re-explaining issues in chat, you can comment on specific lines in the diff, batch those comments, and send them back to Pochi for the right contextual fixes.

This feature is not your regular PR review system. It’s actual conversations with the LLM, attached to the code they refer to.

<video
  controls
  style={{
      width: "100%",
      borderRadius: "8px",
      boxShadow: "0 4px 12px rgba(0, 0, 0, 0.15)",
      }}
>
  <source src="https://assets.docs.getpochi.com/inline-comments.mp4" type="video/mp4" />

  Your browser does not support the video tag.
</video>

## How to Use Reviews

### 1. Run a Prompt

Generate code or request changes like normal.

```bash
Please use Mermaid Chart instead of Vega Lite
```

### 2. Open the Diff

Once Pochi applies changes, open the diff view in VS Code:
![Pochi Models](../assets/images/open-diff-inline-comments.png)

In the diff, hover over a code line and click `+` to add a comment
![Pochi Models](../assets/images/add-comment-inline-comments.png)

### 3. Leave Feedback

Type your comment directly on the line where the issue exists.

![Pochi Models](../assets/images/leave-feedback-inline-comment.png)

### 4. Add Multiple Comments

Leave comments across the file as needed. Each comment is automatically linked to its exact line + file path.

![Pochi Models](../assets/images/multiple-comments-inline-comment.png)

### 5. Send Comments as a Batch

Once you’re done adding comments, submit them just like you would for any other review.

Click `Submit Reviews` to Pochi to send all line-level comments as a batch.

![Pochi Models](../assets/images/submit-review-inline-comments.png)

This works the same way as submitting a review with empty messages, where the comments themselves are the request.

![Pochi Models](../assets/images/submit-review-inline-comment.png)

If you want to add extra instructions or context, you can type an additional message in the chat box before submitting.

For example:

```bash
Please review the feedback
```

or with extra guidance:

```bash
Apply these comments and also rename the handler for consistency
```

Pochi will process every line comment with context and update the code accordingly.


# Rules
URL: /rules
Define coding standards and development guidelines
***

title: Rules
description: Define coding standards and development guidelines
icon: "Ruler"
-------------

# Rules

You can provide custom instructions to Pochi by creating an `README.pochi.md` file. This is similar to CLAUDE.md or Cursor’s rules.

<Callout title="AGENTS.md support">
  Pochi also supports [AGENTS.md](https://agents.md) as an alternative to `README.pochi.md`. Both files serve the same purpose and are treated identically by Pochi.
</Callout>

### Example

Below example is the `README.pochi.md` file for Pochi itself.

```markdown
Pochi is an project developed using following technologies:
1. always use kebab-case for filenames.
2. always use camelCase for variables, functions.
3. use PascalCase for classes, interfaces, types.

# Testing for non packages/vscode
We use vitest framework.
our test use vitest framework.
test command: `bun run test`
coverage test command: `bun run test -- --coverage`

## Testing for packages/vscode
We use mocha framework, when creating test, do not use mocks for filesystem, just use vscode.workspace.fs to create files and folders, and only use mocha primitives for testing. use sinon for mocks.

(assuming cwd is packages/vscode)
test command: `bun run test`
coverage test command: `bun run test:coverage`

When encountering issues like `TypeError: Descriptor for property readFile is non-configurable and non-writable`, please use `proxyquire` to mock the module.

# Misc
1. use `bun check` to format / linting the code, use `bun fix` to automatically apply the fix.
2. use `bun tsc` to check the types.
3. For packages/code it uses `ink` for react terminal ui.
4. Prefer `@/lib` over `../lib` for imports.
5. For global variable in typescript, prefer using PascalCase, e.g `GlobalVariableName`, instead of `GLOBAL_VARIABLE_NAME`.
6. For biome related warning / errors, prefer using `bun fix` in the root directory to fix the issues.
```

## Locations

Pochi looks for rules in two locations:

### Workspace

Pochi first checks for a `README.pochi.md` (or `AGENTS.md`) file in your current workspace root directory. This is where you define project-specific rules that apply only to your current project.

### Global

Pochi also reads global rules defined in `~/.pochi/README.pochi.md`. These rules apply to all projects and are suitable for any personal rules that Pochi should follow.

You can view current active rules in toolbar's token usage popover

<div align="center">
  ![Token Usage](../assets/images/usage-token-popover.png)
</div>


# Share
URL: /share
Share your development context with team members
***

title: Share
description: Share your development context with team members
icon: "Share2"
--------------

# Share

The **Share** feature in Pochi's toolbar allows you to share your current development context with others.

<Callout type="info" title="Public Access">
  Shared conversations are publicly accessible to anyone with the link. Do not share sensitive information or private code.
</Callout>

<div align="center">
  ![Task Sharing](../assets/images/task-sharing.png)
</div>

### How it works

When you share a conversation, Pochi:

1. Persist your task to our servers, and create a unique public URL for the task..
2. Makes task accessible via a link - `app.getpochi.com/share/<shareId>`


# Skills
URL: /skills
Define reusable behavior via SKILL.md definitions
***

title: Skills
description: Define reusable behavior via SKILL.md definitions
icon: "Zap"
-----------

Skills are reusable instruction sets that extend Pochi's capabilities. They allow you to standardize workflows, provide domain-specific knowledge, or integrate with external tools.

## Install Skills

You can discover and install skills from the community [skills.sh](https://skills.sh/) registry using the CLI:

```bash
npx skills add <skill-source> --agent pochi

# Example: Install a specific skill from a collection
npx skills add vercel-labs/agent-skills --skill pr-review --agent pochi
```

This command automatically detects Pochi and installs the skill to `.pochi/skills` in your project. Alternatively, you can place skills in `.agents/skills/` to share them with other AI coding agents.

## Create Skills

To create a custom skill, place a `SKILL.md` file in a subdirectory of `.pochi/skills/`.

**File path:** `.pochi/skills/<skill-name>/SKILL.md`

### Example

Here is an example `SKILL.md` for creating GitHub issues:

```markdown
---
name: create-issue
description: Help create a github issue given the request
---

# Github Issue Creator

1. Search the codebase for relevant context.
2. Create an issue using `gh issue create`.
3. Append the footer: "🤖 Generated with [Pochi](https://getpochi.com)".
4. Assign the issue to the appropriate project.

IMPORTANT: Only create the issue, do not attempt to fix it.
```

### Frontmatter

Each skill must start with YAML frontmatter containing at least a `name` and `description`.

| Field         | Description                                     |
| ------------- | ----------------------------------------------- |
| `name`        | Unique identifier (lowercase, hyphens allowed). |
| `description` | Brief explanation of what the skill does.       |

## Discovery

Pochi automatically discovers skills in the following locations (higher priority listed first):

* **Project**: `.pochi/skills/` (shared with your team, Pochi-specific)
* **Project**: `.agents/skills/` (shared with your team, cross-agent standard)
* **Global**: `~/.pochi/skills/` (available across all projects, Pochi-specific)
* **Global**: `~/.agents/skills/` (available across all projects, cross-agent standard)

If two skills share the same name, the one from the higher-priority location takes precedence.

### Cross-Agent Compatibility

The `.agents/` directory is an emerging standard shared by multiple AI coding agents (e.g., Claude Code, Codex). By placing skills in `.agents/skills/`, you can define shared workflows once and have them available across different agents without duplicating files.

## Using Skills

### Viewing Available Skills

You can view all available skills in your settings panel. This gives you an overview of all installed skills. You can also click the edit button on the right side of each skill to open and modify the corresponding skill file.

![Skills Settings List](../assets/images/skill-setting-list.png)

### Activating Skills

There are two ways to activate skills in Pochi:

#### Automatic Discovery

Pochi can automatically discover and invoke relevant skills based on your prompt. When you describe what you want to do, Pochi will analyze your request and suggest appropriate skills to use.

![Automatic Skill Discovery](../assets/images/skill-automatic-discovery.png)

#### Slash Commands

You can explicitly specify which skill to use by typing a slash command followed by the skill name. This gives you direct control over which skill gets activated.

![Slash Command Usage](../assets/images/skill-slash-command.png)


# Tab Completion
URL: /tab-completion
Inline code completion
***

title: Tab Completion
description: Inline code completion
icon: "Code"
------------

# Tab Completion

**Tab Completion** is Pochi's in-editor inline code completion feature that provides AI-powered suggestions as you type, helping you write code faster and more efficiently.

Pochi uses a state-of-the-art model that adapts to your coding patterns in real time,
drawing on recent edits, diagnostics, and surrounding context to generate helpful,
relevant completions right in your editor.

The suggestion can be rendered as a diff preview, showing exactly what changes will be made to your code.

<div align="center">
  ![Tab Completion showing suggestion via diff](../assets/images/tab-completion-diff.png)
</div>

Alternatively, suggestions can appear as ghost text inline with your code.

<div align="center">
  ![Tab Completion showing suggestion via ghost text](../assets/images/tab-completion-ghost-text.png)
</div>

### Multi-Language Support

Works across popular programming languages including:

* JavaScript/TypeScript
* Python
* Java
* C/C++
* Go
* Rust
* And many more

## Using Tab Completion

Just start typing. Pochi will surface suggestions automatically. The more you use it, the more it understands your codebase, thus suggesting better edits.

### Keyboard Shortcuts

| Key       | Action                                      |
| --------- | ------------------------------------------- |
| `Tab`     | Accept the current suggestion               |
| `Escape`  | Dismiss the suggestion                      |
| `Alt + ]` | Next suggestion (if multiple available)     |
| `Alt + [` | Previous suggestion (if multiple available) |

## Status Bar Item

The status bar item shows the status of Pochi Tab Completion. It indicates whether the feature is enabled, disabled, or if any errors have occurred.

### Disable/Enable

You can click the status bar item to toggle Pochi Tab Completion on and off.

### Feature Conflicts

Pochi's Tab Completion feature may conflict with other extensions that provide code completions, such as GitHub Copilot. If you encounter issues, you can disable conflicting features to use Pochi Tab Completion.

<div align="center">
  ![Resolve Conflicts](../assets/images/tab-completion-resolve-conflicts.png)
</div>

## Tab Completion Model

Pochi uses its own hosted, state-of-the-art tab completion model optimized for speed and accuracy.

We are actively working on allowing you to customize Tab Completion providers in VS Code settings. In future versions, you'll be able to use different models, including those running on your local machine.

***

**Need help?** Join our [Discord](http://getpochi.com/discord) for assistance with Tab Completion features.


# Troubleshooting
URL: /troubleshooting
Common issues and how to resolve them
***

title: "Troubleshooting"
icon: "CircleQuestionMark"
description: "Common issues and how to resolve them"
----------------------------------------------------

# Troubleshooting

To debug any issues with Pochi, you can check the logs from webview console or vscode output console.

### Webview Console

1. Open `Developer: Use Webview Developer Tools` command in VSCode
2. Go to the Console tab
3. Look for error messages related to Pochi

You can configure the log level in VSCode Settings with following snippet

```json
{
  "pochi.advanced": {
      "webviewLogLevel": "DEBUG" // Set to "DEBUG" to see more detailed logs
  },
}
```

### VSCode Output Console

1. Use `Output: Show Output Channels` command in VSCode
2. Select "Pochi" from the dropdown
3. Look for error messages or warnings

# Getting help

If you’re experiencing issues with Pochi:

1. Report issues on Github

   The best way to report bugs or request features is through our GitHub repository: [https://github.com/TabbyML/pochi/issues](https://github.com/TabbyML/pochi/issues)

2. Join our Discord

   For real-time help and community discussion, join our Discord server: [https://getpochi.com/discord](https://getpochi.com/discord)


# VS Code
URL: /vscode

***

title: VS Code
icon: "LayoutPanelLeft"
-----------------------

# VS Code

This page covers the core Pochi experience in VS Code, from installation and setup to the main chat and task management features.

## Installation

Install the Pochi extension from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=TabbyML.pochi) or [OpenVSX](https://open-vsx.org/extension/TabbyML/pochi).

For the best experience, we recommend dragging the Pochi view to the right sidebar to use it side-by-side with your editor.

![Drag the Pochi view to the right sidebar for a side-by-side experience.](../assets/images/vscode-right-sidebar.png)

## Welcome

Upon first launch, Pochi's Welcome page offers two ways to get started:

* **Sign in to Pochi:** Click "Sign In" and authorize in your browser to use Pochi subscriptions, models, and cloud features.
* **Bring Your Own Key (BYOK):** Use your own models by running `Pochi: Open Custom Model Settings` from the Command Palette. This opens `~/.pochi/config.jsonc` for you to add API keys. See [Models](/models) for details.

<div align="center">![The Welcome page provides options to sign in or configure your own models.](../assets/images/welcome-page.png)</div>

## Chat

Access the Pochi chat panel via the Activity Bar icon or shortcut (macOS: `Cmd+L`, Win/Linux: `Ctrl+L`). This is your main interface for interacting with Pochi. **Note:** An active workspace (i.e., an open folder) is required to use the chat.

The panel's title bar includes actions for starting a new task and viewing all tasks.

<div align="center">![The main Chat panel is where you interact with Pochi.](../assets/images/chat-page.png)</div>

## Prompting

The input box, located below the chat history, is where you'll compose your messages and control the chat.

* **Auto-Approve Menu:** This menu at the top of the zone allows you to grant Pochi permission to use tools autonomously, streamlining the workflow.
* **Todo List:** When Pochi creates a to-do list for a task, it will appear here, allowing you to track progress.
* **Chat Input:** The main text area supports both text and image uploads. You can attach files by clicking the **paperclip icon** or by dragging and dropping them into the input area.
* **Bottom Toolbar:** The toolbar at the very bottom provides several key functions:
  * **Model Selector:** Choose which language model you want to interact with.
  * **Token Usage & Compact Task:** Monitor the token count of your conversation. If the conversation becomes long, a **Compact Task** button will appear, allowing you to condense the history and save tokens.
  * **Sharing:** Share your chat session with others (requires a Pochi account).
  * **Submit/Stop Button:** The send button dynamically transforms into a stop button during message generation, allowing you to interrupt the AI at any time.

<div align="center">
  ![The Prompt Zone provides access to key features like model selection and auto-approval.](../assets/images/home-page-toolbox.png)
</div>

## Tasks

A chat session in Pochi is saved as a **Task**. You can view your entire task history from the task list page.

Some AI-powered actions might generate a **Sub-task**, which is a new, focused chat session dedicated to a specific part of the original task.
When you're in a sub-task, you'll see a "Back" button to navigate to the parent task, allowing you to maintain context while breaking down complex problems.
By default sub-tasks are hidden in the task list.

By default, task history is stored locally. Signing in to a Pochi account enables cloud storage for your tasks, along with sharing and team collaboration features.
Be aware that clearing VS Code's extension data may erase your local task history.

<div align="center">![The Task List page shows your historical task sessions.](../assets/images/task-page.png)</div>

## Troubleshooting

Having issues? Here are a few things to check:

* **No Active Workspace:** Pochi requires an open folder to function correctly. Make sure you have a workspace open.
* **Sign-in/Model Configuration:** Verify that you are either signed in to your Pochi account or have a valid API key configured in your `~/.pochi/config.jsonc`.

For more help, check the full [Troubleshooting](/troubleshooting) page or join our community on [Discord](https://getpochi.com/discord).