A local-first AI workbench for project-scoped chats and software work.
Choose a project folder and UMCode keeps its chats and project instructions together. Start a clean chat or a contextual side chat, choose configured provider/model IDs, or combine models into an ordered pool. When a provider reports a quota or rate limit, the engine can continue with the next configured model. Tool actions stay visible, with approvals for sensitive operations.
- Project-aware chats — work in a selected folder with its
UMCODE.mdinstructions - Provider and model choice — use configured models directly or create ordered pools across providers
- Quota-aware routing — move to the next model in a pool when a provider reports a retryable quota or rate-limit failure
- Local controls — keep chat history, model settings, engine status, and approval workflows in one desktop app
- Protected credentials — provider API keys are stored in the macOS Keychain
- Unified plugins — install portable Agent Plugins or compatible Codex and Claude plugin folders containing skills, MCP servers, hooks, and metadata
Requires Go 1.24+ and, for the desktop app, Node.js. See GO_ENGINE.md for the full guide.
make go-build # build the engine + CLI → bin/umcode
./bin/umcode engine # run the engine in the foreground
make app-build # build UMCode.app (macOS)
make help # list all targetsPlugins are the only extension unit shown in the desktop app. Open Plugins, enter a local folder or Git URL, and choose Inspect before Install. Inspection shows the package identity, compatibility diagnostics, executable capabilities, requested settings, and whether additional trust is required. UMCode accepts the portable Agent Plugins plugin.json format, Codex .codex-plugin/plugin.json folders, and Claude .claude-plugin/plugin.json folders.
Managed installs copy verified bytes into ~/.umcode/plugins/cache/<source-id>/<plugin>/<version-or-digest>/, so they keep working if the source disappears. Linked installs track a local source folder and add an explicit Reload workflow for development; each active generation still runs from an immutable cached snapshot, and source edits take effect on reload. Installations and skills are user-global; MCP integrations, hooks, and non-secret settings are per project. Secret settings live in the Keychain or protected secrets file, never SQLite. Mutable plugin data belongs under ~/.umcode/plugins/data/<source-id>/<plugin>/ and is retained on uninstall.
Runtime declarations reference configuration explicitly with {{setting:name}} and protected values with {{secret:name}}. Plugin MCP servers cannot forward arbitrary host environment variables, and sensitive HTTP headers must use a declared secret reference. Skill-script output and hook diagnostics redact resolved secret values. A plugin with required configuration installs disabled for the selected project; configure it, then enable it after its required components activate successfully.
Hooks run commands from the installed package with a minimal environment and bounded input/output. TurnStart and BeforeToolUse may block; no hook can bypass UMCode's built-in guards, policy decisions, or approval prompts. Each turn retains one immutable capability snapshot, so reloading or disabling a plugin affects new turns only.
umcode plugin inspect ./my-plugin
umcode plugin install ./my-plugin --project prj_…
umcode plugin install ./my-plugin --linked --project prj_…
umcode plugin list --project prj_…
umcode plugin enable SOURCE_ID/PLUGIN --project prj_…
umcode plugin reload SOURCE_ID/PLUGIN # linked installs only
umcode plugin remove SOURCE_ID/PLUGIN --disable-projectsLegacy standalone skill commands, skill_dirs, and mcp_servers remain backend-compatible during the migration window, but they are not separate sections in the desktop Plugins screen.
In a main or side chat, type / at the start of a message to find available skills
by name or description. Use ↑/↓ and Enter or Tab, or click a skill, to insert its
command. Add your instructions before sending; selecting a skill does not send
the message. Escape closes the picker. Sending /plugin:skill your request
loads that exact installed skill's instructions in any chat, including chats without a project.
If multiple installed sources share a plugin name, their skill commands include
the source ID (for example, /sourceid.plugin:skill) to distinguish them.
Open Settings → Token optimization to enable the complete optimization system globally: context compilation and retrieval, progressive tools, result reduction, internal workflow tracking and verified memory promotion. All components operate automatically across chats, without separate opt-ins or internal design/planning approval prompts. Chat action permissions still apply.
The saved switch survives restarts and applies to new turns; active turns keep their current settings. Fresh installations start with it off until rollout qualification. Existing YAML feature flags remain effective until you save an explicit global choice; the settings panel identifies legacy or mixed configuration. Saving on enables the whole bundle, and saving off overrides all legacy component flags. Turning it off retains history and stored memory but omits generated memory from subsequent optimized prompt retrieval and stops new promotion. User-written project instructions remain available. Projectless design chats use evidence-linked decisions and completed deliverable tasks; they do not report an execution test pass or human acceptance.
For isolated token optimization regression campaigns and explicit live qualification, see Paired evaluation.
Open Turn details from a response menu to inspect the settings captured when a turn started, its recorded token and cost measurements, context sources, and tool diagnostics. Values the provider or engine did not measure are shown as unavailable; opening the inspector does not make another model call. Legacy turns may not have detailed measurements.
For project knowledge, open Project settings → Memory to review generated and corrected entries. Corrections become user-owned instructions. Retirement removes an unchanged generated bullet when ownership is clear; an edited or user-owned instruction stays in UMCODE.md and remains ordinary project guidance.
The Vault storage controls on Settings → Token optimization show indexed vault objects and bytes, set retention for raw, stale, large, and redacted unreferenced objects, and run Clean up now. Statistics count shared vault objects once and are not total application disk usage. Cleanup reports what it actually deleted and freed; active work evidence and evidence supporting live project memory remain protected. Project-wide purge and forced deletion of referenced evidence are not available. Live paid rollout qualification remains a separate opt-in evaluation.