pocketcoder 1.0.3

AI-powered coding assistant optimized for local LLMs

PocketCoder

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.

---

Quick Start

pip install pocketcoder
pocketcoder

With Ollama (free, local)

# Install Ollama: https://ollama.com
ollama pull qwen2.5-coder:7b
pocketcoder

With OpenAI

export OPENAI_API_KEY="sk-..."
pocketcoder --provider openai --model gpt-4o

---

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:

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

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

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.

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.

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

---

Architecture

How the Agent Loop works

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

---

Commands

Type / to see all commands:

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:

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

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)	0xdF5e04d590d44603FDAdDb9f311b9dF7E5dE797c
BTC	bc1q3q25vw4jm8v4xe2g6uezq35q2uyn5jt6e00mj9
USDT (TRC-20)	TQj3X5nFQWqPEmRUWNFPjkaRUUFLxmCdok
SOL	5s5uP66VmnLMSApjq8ro639tXvSp59XEwQittzxF64mF

---

License

MIT License