percy

Percy: a coding agent

Percy is a fork of Shelley — an awesome foundation built by Bold Software — with a bunch of new features on top.

Percy is a mobile-friendly, multi-conversation, multi-modal, multi-model, single-user coding agent with both a web UI and a terminal UI. It does not come with authorization or sandboxing: bring your own.

Mobile-friendly because ideas can come any time.

Web and terminal UI, because you should use whichever fits your workflow — browser, SSH session, or headless server.

Multi-modal because screenshots, charts, and graphs are necessary, not to mention delightful.

Multi-model to benefit from all the innovation going on.

Single-user because it makes sense to bring the agent to the compute.

What's new in Percy

Memory Search

Percy remembers past conversations. After each conversation ends, messages are automatically chunked and indexed into a separate memory database. The agent can recall earlier decisions, code changes, and context using the memory_search tool. Supports hybrid search combining FTS5 keyword matching with optional vector embeddings (Ollama, or FTS5-only with zero dependencies).

LSP Code Intelligence

Compiler-accurate code navigation powered by Language Server Protocol. The code_intelligence tool gives the agent five operations: definition, references, hover, symbols, and diagnostics. Works with Go (gopls), TypeScript, Python (pyright), Rust (rust-analyzer), and other LSP-enabled languages.

Bundled Skills

14 workflow skills ship embedded in the binary, covering test-driven development, systematic debugging, brainstorming, plan writing and execution, code review, git worktrees, parallel agent dispatch, and more. Skills follow the Agent Skills specification and can be overridden by user or project-level skills.

Skills Discovery

Percy discovers skills from multiple sources: bundled skills, user config directories (~/.config/percy/, ~/.percy/), shared agent skills (~/.config/agents/skills/), project .skills/ directories, and SKILL.md files anywhere in the project tree. Use the /skills command to see what's available.

Programmatic Tool Calling

Inspired by Anthropic's programmatic tool calling, but provider-independent. The scripted_tools tool lets the agent write Python scripts that call Percy's tools programmatically — intermediate tool results stay in the script and only the final print() output enters the conversation context. This dramatically reduces token consumption for multi-tool workflows like scanning many files, running bulk checks, or aggregating data across tools.

# Agent writes this to check 20 files — only the summary enters context
results = []
for path in file_list:
    content = await read_file(path=path)
    if "TODO" in content:
        results.append(path)
print(f"Found {len(results)} files with TODOs: {', '.join(results)}")

Requires uv (Python package manager) in PATH.

Context Window Management

Proactive monitoring of LLM context usage with warnings at 80% capacity, automatic retry on response truncation (up to 2 retries), and increased max output tokens (16,384) for longer responses.

Conversation Distillation

When a conversation gets long, Percy can distill it into an operational brief and continue in a fresh conversation. The distillation preserves files modified, decisions made, current state, and next steps — everything the agent needs to pick up where it left off.

Terminal UI (TUI)

percy tui launches a Bubble Tea terminal client that connects to a running Percy server via HTTP/SSE. List conversations, chat with streaming responses, markdown rendering, and all the key bindings you'd expect. The TUI is a pure HTTP client — it runs as a peer to the web UI, and both can be open simultaneously against the same server.

# Start the server
./bin/percy serve

# In another terminal
./bin/percy tui
./bin/percy tui --server http://myhost:8080  # custom server URL

MuninnDB Augmentation (Optional)

Percy can optionally push memories to a MuninnDB server and include its context-aware activations in search results. This enables cross-agent memory sharing on a LAN — what one Percy instance learns becomes available to all others. MuninnDB adds temporal decay (recently-used memories rank higher), Hebbian association (co-retrieved memories form automatic links), and predictive activation on top of Percy's local FTS5 search.

# Start MuninnDB (Docker)
docker run -d --name muninndb -p 8475:8475 ghcr.io/scrypster/muninndb:latest

# Configure Percy
export PERCY_MUNINN_URL=http://192.168.1.67:8475
export PERCY_MUNINN_VAULT=percy        # optional, default: percy
export PERCY_MUNINN_TOKEN=your-token   # optional, default: empty

Local SQLite memory remains primary. MuninnDB is additive — if unreachable, Percy operates normally.

Markdown Table Rendering

Agent responses containing markdown tables are rendered as styled, readable HTML tables — bordered, with header highlighting, column alignment, hover rows, and horizontal scroll on mobile. No external markdown library needed; a lightweight built-in parser handles detection and rendering while leaving the rest of the text untouched.

Notification Channels

Get notified when the agent finishes work. Supports Discord webhooks and email, with a test endpoint to verify connectivity. Channels are configurable via the API and persist in the database.

Installation

Pre-Built Binaries (macOS/Linux)

curl -Lo percy "https://github.com/tgruben-circuit/percy/releases/latest/download/percy_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')" && chmod +x percy

The binaries are on the releases page.

Homebrew (macOS)

brew install --cask tgruben-circuit/tap/percy

Build from Source

You'll need Go and Node.

git clone https://github.com/tgruben-circuit/percy.git
cd percy
make

Architecture

The technical stack is Go for the backend, SQLite for storage, TypeScript and React for the web UI, and Bubble Tea for the terminal UI.

The data model is that Conversations have Messages, which might be from the user, the model, the tools, or the harness. All of that is stored in the database, and we use a SSE endpoint to keep the UI updated.

Acknowledgments

Percy stands on the shoulders of Shelley by Bold Software. Shelley provided the solid core — the agentic loop, multi-model LLM integration, tool execution, SSE-based UI, and the mobile-friendly web interface. We're grateful for that foundation.

Shelley was itself partially based on Sketch.

Open source

Percy is Apache licensed. We require a CLA for contributions.

Building Percy

Run make. Run make serve to start Percy locally.

Dev Tricks

If you want to see how mobile looks, and you're on your home network where you've got mDNS working fine, you can run

socat TCP-LISTEN:9001,fork TCP:localhost:9000