Local-First AI Coding Harness

Real coding agents for the GPU you already own.

Most coding agents assume a frontier cloud model with a massive context window. Pedacito (pdc) cuts your codebase into small, AST-indexed pieces so local models read, verify, and edit only the lines that matter.

GUI, TUI, CLI & JSONL-RPC Local-First + Optional Cloud Escalation Cross-Platform (Linux, macOS, Windows) Bilingual English & Español (EN | ES)
quickstart
# Install and launch the browser control panel
$ pip install pedacito
$ pdc gui ~/code/your-project
# Or stay in the terminal with split-screen TUI
$ pdc models scan
$ pdc tui ~/code/your-project
[index] AST map ready, prefix cache warm
[gate] syntax, contracts & scoped tests verified
[saved] checkpoint recorded (pdc undo to rewind)
Local OpenAI-compatible runtimes & hosted APIs
LM Studio Ollama llama.cpp Lemonade Server vLLM Strata / Avalon MoE Anthropic /v1/messages Hosted APIs (Optional)
Core Philosophy

Engineered for precision, not brute-force context.

Every design choice in Pedacito is judged on one question: does it raise task success and answer faithfulness per token and per second on local hardware?

01 / TOKEN ECONOMY

Small, exact pieces instead of whole files

Pedacito builds an AST-derived index of your repository so a compact local model navigates directly to the relevant symbols and line ranges. It reads only what it needs, once, rather than burning VRAM on noisy transcripts.

02 / DETERMINISTIC FIRST

Verify mechanically before paying for another model call

Code correctness can be checked against source and tests for free. Pedacito runs in-process AST syntax gates, cross-file signature locks, static checks, and web DOM contract checks automatically, reserving model tokens for real judgment.

03 / CACHE DISCIPLINE

Prompt-prefix cache preservation by design

Local servers pay a steep prefill tax whenever conversation history is rewritten. Pedacito uses append-only evidence logs, grammar-enforced JSON schemas, and surgical repair-turn collapse so your server's KV cache stays hot across steps.

04 / BOUNDED & REVERSIBLE

Hard leases, green ratchets, and instant undo

No runaway loops and no silent half-broken trees. Every run has bounded recovery ceilings, automatic rollback when a multi-step edit fails verification, and time-travel checkpoints you can inspect or restore in one command.

Architecture

From repository map to verified patch.

A structured, harness-managed loop keeps small models grounded in real code from disk.

1

AST Index & Ranked Map

Tree-sitter and Python AST chunk your project into semantic units with call graphs, import graphs, and persisted lexical sidecars. Pin exact context anytime with @file or @Class.method.

2

Grammar-Guided Gather

The model explores using constrained JSON tool calls (read, grep, outline, usages, scoped run_test) while a content-addressed evidence store tracks every exact line shown.

3

Surgical Edit & Gate Verification

Edits land via exact search/replace or zero-anchor AST symbol splicing, then pass syntax, static, cross-file contract, and test gates before writing with an automatic checkpoint.

Key Capabilities

Everything you need for daily local-first development.

Built to scale smoothly from a single laptop GPU to multi-server home labs and hybrid local-plus-cloud setups.

GUI, Split-Screen TUI & CLI

Use the offline browser control panel with side-by-side diffs and live HTML preview, the multi-line split-screen TUI with bracketed paste, headless --json automation, or warm stdio JSONL-RPC.

VRAM Pool & System Auto-Tune

Treats local servers as one pool with Lemonade model pinning and automatic eviction. pdc profile reads RAM/VRAM across Linux, macOS, and Windows, and opt-in auto_tune fits budgets to free memory.

Hybrid & Specialist Routing

Pair an Architect model with a fast local Editor, assign a lightweight Scout for lookups, or auto-route tasks to coding, UI, SQL, and testing specialists.

2-Model Sandbox Arena

Pit two models against each other on the same prompt inside isolated workspace sandboxes. Compare unified diffs, speed, and tokens, then apply the winner safely.

Time-Travel Checkpoints

Every Task, Auto step, and scaffold records an append-only snapshot checkpoint. Inspect unified diffs, restore a single file or whole workspace, and branch prompts from any state.

Security & Secret Guard

Scans outbound prompts for API keys and credentials, enforces strict workspace path containment, pins DNS against rebinding, and gates risky actions with a human broker.

Model Calibration & Benchmarks

Measure local models on your own hardware with empirical micro-probes and a built-in diagnostic benchmark suite graded against hidden holdout rubrics.

SSE Streaming & Live Telemetry

Watch tokens and reasoning stream live with a millisecond Stop button, context utilization meter, generation speed (tok/s), and KV cache hit ratio.

Skills, Rules & Zero-Token Refactoring

Load built-in or custom skill checklists, enforce persistent project rules in .pedacito/rules.md, and rename symbols across files with zero LLM calls.

Multimodal Input & Local Image Gen

Paste or attach screenshots (Ctrl+V, --image, /attach) for local VLMs and hosted models, or generate local assets via pdc image on Lemonade Server (sd-cpp) and OpenAI-compatible image backends.

Native Anthropic Caching & Hybrid Cloud

Speaks native Anthropic /v1/messages with explicit cache_control breakpoints, extended thinking, and tool calls—plus prompt caching across DeepSeek, OpenAI, Qwen, and Gemini with strict spend caps.

Bilingual EN / ES & Quiet Updates

Switch instantly between English and neutral Latin American Spanish via the GUI EN | ES toggle, TUI F3 / /lang, or CLI --lang es, with full Spanish docs and opt-out pdc update.

Workflows

Adapt the harness to your hardware.

Start with one local model and grow into multi-model orchestration whenever you want.

Fast, private coding on one card

Auto-fit sizes your context budgets to your real VRAM and KV cache. Dry-run diffs first, inspect side-by-side changes, and apply with automatic backups.

  • Auto-discovers LM Studio, Ollama, Lemonade, and llama.cpp servers
  • Calibrates tool choice, edit format, and thinking toggles per model
  • Supports tiered MoE engines with dedicated single-stream profiles
# Discover and calibrate local models
$ pdc models scan
$ pdc calibrate --all

# Review a proposed change before writing
$ pdc ask . -t "add retry backoff to client.py" --review

# Rewind anytime
$ pdc undo .

Split planning from fast local execution

Let a high-reasoning Architect model (local or hosted with a spend cap) produce an exact blueprint, then hand execution to a fast local Editor model.

  • Native VRAM handoff evicts the outgoing local server between stages
  • Pair a small Scout model on a second GPU for rapid repository lookups
  • Route specialized tasks (coding, UI, SQL, QA) to measured specialists
# Inside the split-screen TUI
pdc> /hybrid big deepseek-chat
pdc> /pin add src/router.py
pdc> /pin add RouteTable.dispatch

# Or run an autonomous checklist with specialist routing
$ pdc auto . -t "add CSV export with tests" \
    --auto-route --verify "pytest -q" --apply

Compare two models without touching your repo

Run the exact same prompt across two contestants in isolated workspace sandboxes. Inspect both diffs, token counts, and speed side by side before adopting a winner.

  • Real workspace stays completely untouched during the comparison
  • Automatic VRAM handoff between local contestants on shared hardware
  • Applying the winner wraps the change in pre and post checkpoints
# Pit two profiles head-to-head in isolated sandboxes
pdc> /arena coder-a coder-b refactor parser error handling

Contestant A: 2 files changed | 48.2 tok/s | 14.1s
Contestant B: 2 files changed | 39.7 tok/s | 18.4s

# Adopt the winner with an undoable checkpoint
pdc> /arena apply a

Ready to put your local GPU to work?

Download, install, and read the full documentation, model guide, and architecture notes on GitHub. Open source under the MIT License.