pocketcoder 1.0.4
AI-powered coding assistant optimized for local LLMs
Requires Python: >=3.8
Keywords: ai, assistant, coding, llm, ollama

# PocketCoder

[![PyPI version](https://img.shields.io/pypi/v/pocketcoder.svg)](https://pypi.org/project/pocketcoder/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

**CLI coding assistant supporting Ollama, OpenAI, Claude.**

Features session persistence, multi-step task planning, project-aware context (RepoMap), and interactive file editing with human-in-the-loop approval.

<p align="center">
  <img src="https://raw.githubusercontent.com/Chashchin-Dmitry/pocketcoder/main/assets/screenshots/01_startup.png" alt="PocketCoder CLI" width="700">
</p>

---

## Quick Start

```bash
pip install pocketcoder
pocketcoder
```

<details>
<summary><b>With Ollama (free, local)</b></summary>

```bash
# Install Ollama: https://ollama.com
ollama pull qwen2.5-coder:7b
pocketcoder
```
</details>

<details>
<summary><b>With OpenAI</b></summary>

```bash
export OPENAI_API_KEY="sk-..."
pocketcoder --provider openai --model gpt-4o
```
</details>

---

## Key Features

- **Multi-provider** — Ollama, OpenAI, Anthropic, vLLM, LM Studio
- **Session memory** — agent remembers context across requests
- **Task planning** — TODO tracking with automatic breakdown
- **RepoMap** — project structure awareness for better context
- **Human-in-the-loop** — approve/reject every file change
- **Offline capable** — works fully local with Ollama

---

## Demo: Building a Calculator

Ask PocketCoder to create a GUI calculator — it plans, asks clarifying questions, writes code, and runs it:

<p align="center">
  <img src="https://raw.githubusercontent.com/Chashchin-Dmitry/pocketcoder/main/assets/screenshots/05_thinking_question.png" alt="Agent asks clarifying question" width="700">
</p>

*Agent reasons about the task and asks what type of calculator you need*

<p align="center">
  <img src="https://raw.githubusercontent.com/Chashchin-Dmitry/pocketcoder/main/assets/screenshots/06_write_preview.png" alt="Code preview before writing" width="700">
</p>

*Shows code preview before writing — you approve with [y] or skip with [n]*

<p align="center">
  <img src="https://raw.githubusercontent.com/Chashchin-Dmitry/pocketcoder/main/assets/screenshots/08_calculator_result.png" alt="Working calculator" width="700">
</p>

*Result: working tkinter calculator created and executed*

---

## Features

### Session Memory
Agent remembers what you're working on across requests. No need to re-explain context.

### Project Awareness
RepoMap shows your codebase structure to the LLM. Agent knows your file layout.

### Multi-step Tasks
TODO tracking with automatic planning. Agent breaks complex tasks into steps.

<p align="center">
  <img src="https://raw.githubusercontent.com/Chashchin-Dmitry/pocketcoder/main/assets/screenshots/04_session_context.png" alt="SESSION_CONTEXT" width="700">
</p>

*SESSION_CONTEXT: what the LLM sees about your project*

### Human-in-the-loop
Every file write requires your approval. Ask questions, reject changes, cancel tasks.

<p align="center">
  <img src="https://raw.githubusercontent.com/Chashchin-Dmitry/pocketcoder/main/assets/screenshots/09_task_control.png" alt="Task control" width="700">
</p>

*Full control: reject changes, explain why, cancel entire task*

---

## Architecture

<p align="center">
  <img src="https://raw.githubusercontent.com/Chashchin-Dmitry/pocketcoder/main/assets/architecture.png" alt="PocketCoder Architecture" width="600">
</p>

<details>
<summary><b>How the Agent Loop works</b></summary>

1. **Task Initialization** — TaskSummarizer captures your goal
2. **Reconnaissance Rule** — READ before WRITE, never blind edits
3. **RepoMap** — Automatic codebase structure (gears by project size)
4. **Tool Execution** — Execute tools, get raw results
5. **ContentPreview** — Smart summarization (LLM sees actual code)
6. **State Tracking** — FileTracker + TodoStateMachine
7. **Episodic Memory** — Checkpoint progress, search history
8. **SESSION_CONTEXT** — XML with files, task, repo_map, todo, history
9. **REFLECT prompt** — Self-check before next iteration
10. **Parser** — Auto-sync KNOWN_TOOLS with available tools

</details>

---

## Commands

Type `/` to see all commands:

<p align="center">
  <img src="https://raw.githubusercontent.com/Chashchin-Dmitry/pocketcoder/main/assets/screenshots/02_commands.png" alt="Commands menu" width="600">
</p>

| Command | Description |
|---------|-------------|
| `/help` | Show available commands |
| `/model` | Switch LLM model |
| `/add <file>` | Add file to context |
| `/drop <file>` | Remove file from context |
| `/files` | List files in context |
| `/undo` | Undo last file change |
| `/clear` | Clear conversation history |
| `/quit` | Exit |

---

## Supported Providers

| Provider | Type | Setup |
|----------|------|-------|
| **Ollama** | Local | `ollama serve` then `ollama pull model` |
| **OpenAI** | Cloud | Set `OPENAI_API_KEY` |
| **Anthropic** | Cloud | Set `ANTHROPIC_API_KEY` |
| **vLLM** | Local/Cloud | Any OpenAI-compatible endpoint |
| **LM Studio** | Local | Run server, point to localhost |

---

## Recommended Models

For local use with 16GB+ RAM:

| Model | Size | Speed | Quality |
|-------|------|-------|---------|
| `qwen2.5-coder:7b` | 4.7GB | Fast | Good |
| `qwen2.5-coder:14b` | 9GB | Medium | Better |
| `deepseek-coder:6.7b` | 4GB | Fast | Good |
| `codellama:13b` | 7GB | Medium | Good |

---

## Configuration

Config stored in `~/.pocketcoder/config.yaml`:

```yaml
provider:
  type: ollama
  base_url: http://localhost:11434
  default_model: qwen2.5-coder:7b

thinking:
  mode: smart           # smart | always | never
  show_reasoning: true  # show agent's thinking process
```

---

## Project Structure

PocketCoder stores session data in `.pocketcoder/` directory:

```
.pocketcoder/
  project_context.json  # Current session state
  episodes.jsonl        # Conversation history
  memory.json           # Long-term facts
```

---

## Development

```bash
git clone https://github.com/Chashchin-Dmitry/pocketcoder.git
cd pocketcoder
pip install -e ".[dev]"
pytest
```

---

## Support the Project

If PocketCoder saves you money on AI subscriptions, consider supporting development:

| Network | Address |
|---------|---------|
| ETH / USDT (ERC-20) | `0xA7BdDcf2D576308E14346B0C029a120d45a5AcD7` |
| BTC | `bc1q3ylca90wneas5e8mtx2wzav22cgqcajst5szaf` |
| USDT (TRC-20) | `TB31Y8jhe8JRn5YRL1NnVzL8pka1PwqJvU` |
| SOL | `J4YBJXyWGnACM2nF35x11WiRxjHLM8nopg8fGZzrjkT` |

---

## License

MIT License