Minimalist Agent

A focused AI coding agent for software engineers who value simplicity.

Work with GitHub Copilot, ChatGPT, CodeMie, or local models through a clean desktop interface. Full tool access, intelligent collaboration, built-in terminal, git integration, and powerful search — all without the bloat.

Minimalist Agent is built for its author, first. It's tailored directly to the needs I actually have — not a feature checklist chasing every use case.

The guiding rule is simple: more features means more maintenance, and that's not fun. So the project moves forward with only the functionality that's genuinely needed, and everything that ships is owned — understood end to end, maintained deliberately, and built in-house rather than left floating around as a half-wired dependency or a feature nobody fully grasps.

That's the whole point of the name. Minimalism here isn't a constraint to apologize for — it's the design. If something doesn't earn its keep, it doesn't make the cut.

• GitHub Copilot — device-flow OAuth; live model discovery (Claude, GPT-5, GPT-5.1, and more); Copilot quota display
• ChatGPT Plus / Codex — browser OAuth; live model discovery via Pi SDK; full permission modes and tool streaming
• OpenAI-compatible providers — StepFun, DeepSeek, Moonshot, Together AI, Groq, OpenRouter, xAI, or any custom endpoint; curated presets with live model discovery from /v1/models; encrypted API key storage
• CodeMie SSO — EPAM browser SSO with encrypted session cookies, project and LiteLLM integration selection, model refresh, and project-budget display
• Local model (Ollama) — connect to any Ollama endpoint; live model discovery; no auth required

• Full toolset — Read, Write, Edit, Bash, Grep, Glob, WebFetch, WebSearch, Agent — Pi's own built-in tool set
• In-app browser (browser_tool) — drive a real, visible Chromium window (one per session) to navigate, click, fill forms, screenshot, and read console/JS output on a running app
• Multi-phase planning — complex tasks broken into phases with progress tracking, per-phase approval, and plan revision based on discoveries
• Phase-level approval workflow — configure when phases require approval based on risk level and autonomy settings
• Subagents — Agent tool spawns subagents within a turn; parallel execution with git worktree isolation
• Permission modes — Plan (read-only) · Approve (require approval per phase) · Auto (intelligent execution with autonomy slider)
• Intelligent collaboration — 0-100% autonomy slider controlling how often the agent asks for decisions, approvals, and feedback
• Mid-turn steering — inject a message (with attachments) into a live turn without cancelling it (Cmd+Enter)
• Continue after max turns — one-click resume when the agent hits max_turns
• Thinking / reasoning — extended thinking with collapsible panels
• Compaction — persistent inline divider at compaction boundaries with token delta; survives reload

• Persistent sessions — full message history (messages.jsonl + session.json); resume across restarts
• Session export & sharing — export to HTML (summary or full); save locally or publish ephemeral share links with configurable TTL; revoke anytime; paths and secrets are redacted on share
• Projects — group sessions by folder with name + color; per-project connection, model, permission mode, and Co-Authored-By defaults
• Conversation branching — fork a new session from any user message in history
• Bulk session actions — select multiple sessions to delete or archive at once
• User Preferences — name, timezone, location, language, free-text notes injected into every turn
• Project context — auto-discovers CLAUDE.md / AGENTS.md / copilot-instructions.md recursively

• Voice dictation (Cmd+Shift+M) — on-device speech-to-text in the composer (sherpa-onnx + Moonshine, CPU inference); streaming transcription inserted at cursor; model downloads once on first use, fully offline after that; audio never leaves the machine
• Terminal (Cmd+T) — full in-app terminal (xterm.js + node-pty); real PTY, multiple tabs, in-terminal search, copy-on-select, URL click-to-open, 2 MB scrollback; three bundled fonts
• File Explorer (Cmd+B) — collapsible file tree panel with virtual scrolling for high performance with large directories; gitignore-aware, keyboard navigation, context menu (Copy Path / Reveal in Finder); persistent state across sessions
• Git diff review (Cmd+G) — full-screen Monaco DiffEditor; file list with M/N/D/R status; per-repo branch labels; collapsible file sections; hunk-level staging; commit panel with amend support; multi-repo workspace

• Search Everywhere (double-tap Shift) — unified file name + content search; bundled ripgrep for fast full-text search; smart file viewer (Markdown, images, JSON tree, syntax-highlighted code)
• Recent Files (Cmd+E) — palette of the 30 most recently opened files, type to filter
• Keyboard shortcut map — Settings → Shortcuts panel with every keybinding

• MCP servers — stdio + HTTP/SSE transports; consent gate; encrypted secrets per extension
• CLI-bound & guide-only extensions — drop a directory into <userData>/extensions/
• Skills — reusable SKILL.md instruction sets invoked with @slug
• @-mention picker — extensions and skills surfaced alongside files in the mention picker

• Rich code blocks — Shiki syntax highlighting; expand-to-fullscreen on every block
• Mermaid diagrams — rendered SVG with zoom/pan, copy raw source, expand modal
• KaTeX math — $$...$$ expressions rendered as typeset equations
• JSON tree viewer — collapsible interactive tree for tool results and structured data
• Datatable renderer — ```datatable fenced blocks render as interactive tables
• Inline diffs — unified diff + split-view modal for Edit/Write tool calls
• Smart snippet attachments — large clipboard pastes auto-converted to named snippet chips with language detection and inline preview
• Turn duration — elapsed time displayed in each message bubble
• Auto-update — ships new releases automatically via GitHub Releases

Get the latest release for your platform from the Releases page.

1. Launch the app (see macOS Gatekeeper note below if blocked)
2. Add a connection — Settings → Connections
   • GitHub Copilot — Sign in via device flow
   • ChatGPT — Sign in via browser OAuth
   • OpenAI-compatible — Choose a preset (StepFun, DeepSeek, Moonshot, Together AI, Groq, OpenRouter, xAI) or enter a custom endpoint; paste your API key
   • CodeMie SSO — Sign in with EPAM SSO, then select a CodeMie project, optional LiteLLM integration, and model
   • Local — Point to your Ollama endpoint
3. Start chatting — Cmd+N for new session

The macOS build is currently unsigned. On first launch macOS will block it.
To open: right-click the app → Open → Open (you only need to do this once).

Alternatively:

xattr -d com.apple.quarantine /Applications/Minimalist\ Agent.app

Prerequisites: Node 22+, Bun (or npm)

git clone https://github.com/thehope2k/minimalist-agent.git
cd minimalist-agent
bun install
bun run dev        # dev mode with HMR
bun run typecheck  # type-check only
bun run pack       # local build → release/

See CONTRIBUTING.md for the full development guide.

• Electron + electron-vite
• React 18 + TypeScript
• Tailwind CSS v4
• @earendil-works/pi-coding-agent (GitHub Copilot, ChatGPT Plus, CodeMie, OpenAI-compatible providers)
• xterm.js + node-pty (terminal)
• Monaco Editor (git diff / file viewer)
• @vscode/ripgrep (Search Everywhere)
• Radix UI (tooltips, popovers)

• Multi-provider — switch between GitHub Copilot, ChatGPT, CodeMie, and local models from one interface
• Developer-first — built-in terminal, git diff viewer, file explorer, and powerful search
• Intelligent collaboration — adjustable autonomy from "ask me everything" to "just get it done"
• Planning workflow — break down complex tasks into phases with approval and revision
• Privacy-focused — local storage, encrypted secrets, no telemetry by default (optional local OpenTelemetry tracing is opt-in)
• Extensible — MCP servers, CLI-bound extensions, and reusable skills
• Open source — MIT licensed, built with modern web tech

• Changelog — what's new in each release
• Roadmap — what's in, what's coming, what's out of scope

• Architecture — agent pipeline, event flow, storage layout
• System Prompt — every prompt block, token budget, and the rules for changing it
• OpenAI-Compatible Providers — presets, custom endpoints, model discovery
• CodeMie SSO — EPAM SSO setup, projects, models, and budget display
• Session Export & Sharing — HTML export, share links, redaction
• Agent Definitions — reusable agent configurations and sub-agent system
• Collaboration — autonomy system and intelligent engagement
• Terminal — in-app terminal reference
• Browser Tool — in-app browser automation reference
• Worktree Isolation — parallel agent isolation via git worktrees
• OpenTelemetry Tracing — opt-in spans for agent turns, model requests, and tool calls

• Contributing — development setup and guidelines
• Security — vulnerability reporting

MIT © 2026 The Hope