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.
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).
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.
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.
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.
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.
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.
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.
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 URLPercy 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: emptyLocal SQLite memory remains primary. MuninnDB is additive — if unreachable, Percy operates normally.
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.
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.
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 percyThe binaries are on the releases page.
brew install --cask tgruben-circuit/tap/percyYou'll need Go and Node.
git clone https://github.com/tgruben-circuit/percy.git
cd percy
makeThe 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.
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.
Percy is Apache licensed. We require a CLA for contributions.
Run make. Run make serve to start Percy locally.
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