The customizable coding terminal.

MendCode is a terminal-first coding-agent harness you can make your own: a
public mendcode CLI, configurable model roles, review gates, Changes Review,
Memory Center, Plan Mode Markdown, Agent View, reusable team packages, project MCP config,
mflow/worktree coordination, Usage Insights, release/security gates, and a
customizable TUI for home identity, prompt chrome, widgets, panels, dialogs, and
themes without patching runtime internals. Local agents can also control the
same session runtime through versioned JSON commands for progress, waiting, and
cancellation.

Website · Docs · Feature map · Acknowledgements

Contents

• Why It Exists
• Install
• First Run
• Product Surfaces
• Documentation Map
• Development
• Community And Security
• For Agents
• Lineage

Why It Exists

Most coding agents give you a chat box. MendCode gives you the harness around it:

The short version: MendCode is not just "run a model in a terminal." It is a
configurable coding terminal with packaging, review, memory, permissions, and
coordination built into the workflow.

Install

Choose the row for your shell:

The public command is mendcode. Development checkouts may contain a local
mend shim for legacy/internal workflows, but public docs, examples, and
screenshots should use mendcode.

First Run

After installation, open MendCode in your repo:

mendcode

On first launch, MendCode opens the setup screen. Use it to configure the
harness once: provider/auth, model roles, budget posture, package state, TUI
profile, prompt mode, memory, and permissions. Once setup is complete, use the
commands below for everyday work:

Useful commands after setup:

Product Surfaces

Custom Terminal UI

MendCode turns the terminal into a configurable product surface: home identity,
prompt frame, prompt marker, status row, split panels, Agent View, action
menus, chat presentation, widgets, slots, custom routes, dialogs, footer
entries, and themes.

{
  "identity": {
    "logoMode": "mascot",
    "productName": "MendCode"
  },
  "surfaces": {
    "homeWelcome": {
      "mode": "split",
      "rightPanel": "agentManager"
    }
  },
  "promptChrome": {
    "preset": "top-bottom",
    "glyphs": {
      "leadText": "mendcode>"
    }
  },
  "promptStatus": {
    "placementByPreset": {
      "top-bottom": "outside",
      "ascii-box": "inside"
    }
  }
}

Ctrl+P -> Home identity
Ctrl+P -> Home welcome mode
Ctrl+P -> Home split panel
Ctrl+P -> Prompt chrome
Ctrl+P -> Prompt lead string
Ctrl+P -> Prompt status placement
Ctrl+P -> Chat presentation
Ctrl+P -> Usage Insights

Marketplace Your Harness

A MendCode marketplace package captures the reusable parts of a team setup:

.mendcode/
  agents/
  commands/
  modes/
  skills/
  prompts/
  plugins/
  tools/
  pages/
  tui/
  widgets/

Packages can include MCP config, context docs, scripts, TUI profiles, theme
tokens, custom tool calls, custom TUI pages, shell-backed widgets, model roles,
focus defaults, budget posture, permission defaults, memory defaults, and
worktree policy.

Packages must not include provider tokens, OAuth state, .env*,
.mendcode/auth, local databases, room secrets, or machine-local cache/run
state.

mendcode marketplace create --id acme-standard --title "Acme Standard" --include skills,modes,plugins,tools,pages
mendcode marketplace list
mendcode install acme-standard
mendcode marketplace install acme-standard
mendcode marketplace enable acme-standard

Plan Mode

Plan Mode is for users who want the agent to think first without silently
editing files.

1. The planning agent researches and writes a Markdown plan.
2. MendCode renders the plan in a TUI modal.
3. The user can approve, edit, comment, reject, or close.
4. Approval switches into the configured implementation agent.
5. The reviewed Markdown becomes the source of truth for implementation.

See Plan Mode.

Changes Review

Changes Review opens the current working-tree diff inside the TUI. It is a
review workspace, not just static patch text: move by file, hunk, or line; add
comments; reload the diff; then press Esc or q to return to chat without
stopping the active session.

/changes

When the view is active, MendCode gives the assistant bounded review context on
model turns: selected file/hunk/line, comments, stale comment count, and compact
file summaries. Comments added while an agent is working become visible to the
agent on the next model turn, including after a tool call completes. MendCode
does not splice new comments into an already-running token stream.

See Changes Review.

Loop Workflows

Loop Workflows are durable, monitorable loop sessions for objectives that should
keep moving across controlled iterations. Completion semantics and wakeup
cadence are separate, so the same runtime supports three clear shapes:

A recurring job still has an objective, but the objective describes what each
wakeup should do rather than acting as an early-completion condition. A loop
starts from /loop, is supervised in /loops, becomes an activated root
session, records run/journal events, appears in Agent View, and can be woken
manually or by a per-project background service. The dashboard keeps its next
wakeup countdown live, shows scheduler health and evidence, and makes durable
needs_input permission waits visible instead of presenting them as failures.

mendcode loops examples
mendcode loops draft --template research-digest --name "Loop test"
mendcode loops activate loop_...
mendcode loops tick loop_... --execute --report-only
mendcode loops monitor loop_...

For a workflow whose durable contract is already report-only/read-only,
--execute --report-only wakes the agent and writes transcript activity without
edit/write/patch/shell/subagent tools. Edit-capable workflows keep their
contract; full execution remains explicit through --execute or
mendcode loops service start --allow-edits.

See Loop Workflows.

Memory With Control

MendCode memory is approval-first by design. It can retrieve useful project
context without turning every session into permanent state.

• global and project scopes
• explicit mendcode memory add
• mendcode memory search and mendcode memory preview
• generated memory proposals
• apply, reject, and edit proposal flow
• transient prompt injection through bounded memory context

The Memory Center view brings saved memories, pending proposals, categories,
Dream state, project grouping, and a constrained memory side chat into one
reviewable workspace. See Memory Center.

Usage Insights

Usage Insights is local observability for the coding harness, not cloud
analytics and not a productivity claim.

It can show global/project/directory scope, token heatmaps, sessions, active
days, prompt volume, AI generation time, tool runtime, changed files, top tools,
top agents, top models, cache mix, and optional weather.

See Usage Insights.

Coordination: mflow, TSM, Worktrees

MendCode includes optional coordination for people running multiple terminal
sessions around the same codebase.

mendcode mflow setup
mendcode worktree plan feature-branch
mendcode worktree create feature-branch
mendcode tsm setup

Documentation Map

Development

This repository contains the MendCode-owned runtime under src/mendcode/.
Focused development usually happens in src/mendcode/packages/opencode.

Useful commands from an existing checkout:

cd src/mendcode/packages/opencode
bun test --timeout 30000
bun run typecheck
bun run build

The root src/mendcode package intentionally does not use bun test as the
normal test entrypoint; run focused tests from the package that owns the change.

Community And Security

• Contributing: local development, PR expectations, and review flow.
• Security policy: supported reporting path for security issues.
• Community docs: issues, discussions, labels, and contribution guidance.
• Release process: release assets, checksums, installer smoke tests, and public promotion.
• Supply chain security: provenance, dependency review, scanners, and release hardening.

For Agents

If you are an agent working in this repository, use this short path first:

1. Read the source-level contributor contract.
2. Use the public mendcode CLI and verify live source before documenting behavior.
3. Run focused checks from the package that owns the change; do not run tests from
   the repository root.
4. Keep changes minimal and never include provider tokens, auth state, or local
   runtime data in packages, screenshots, or docs.

Agent theme workflow

When a user provides an image or visual reference, convert it into deterministic
theme JSON using the built-in color keys, then run the supported local flow:

mendcode theme validate ./my-theme.json
mendcode theme install ./my-theme.json --name studio --scope project
mendcode theme select studio --scope project

Project themes belong in .mendcode/themes/ and the selection belongs in
.mendcode/tui.json; --scope global uses the XDG MendCode configuration
directory (Global.Path.config). Validation resolves references and variants,
rejects missing or circular references, and checks 3:1 text/background contrast
when hex colors can be resolved. Do not use kv.json as a substitute. See
Themes for the complete format. These commands are local-only
and do not call a model or provider.

This block is intentionally collapsed so the README stays readable while still
giving coding agents MendCode context before editing docs, website copy, CLI help,
screenshots, or public claims. Treat it as context, then verify live code before
changing behavior.

Public identity

• Product name: MendCode.
• Public command: mendcode.
• Local development checkouts may include a legacy mend shim. Public docs,
  examples, screenshots, release notes, website copy, and user-facing commands
  should use mendcode unless the router contract changes.
• MendCode is a downstream project built on opencode, with attribution in
  ACKNOWLEDGEMENTS.md. Do not present it as a simple
  rename.

Public CLI contract

• Source of truth: src/mendcode/packages/opencode/src/mend/cli/public-bin.ts.
• Re-run public help before adding command examples.
• Primary public surfaces include opening the TUI, run, session, chat,
  status, doctor, setup, marketplace, mflow, worktree, and tsm.
• Automation details live in docs/automation-runtime.md:
  mendcode.cli.v1 JSON envelopes, session lifecycle commands, progress events,
  bounded waiting, cancellation, secret redaction, and shared model/agent
  selection. It is a wrapper over the existing runtime, not a second provider
  or session implementation.
• Support surfaces include models, providers, auth, permissions,
  memory, and focus.
• Internal debug surfaces such as adapter, ai, bench, budget, config,
  context, export, mcp, prompt, prompts, runtime, toolchain,
  tui, and upstream should not be marketed as normal user workflows.

Core product story

• MendCode is the customizable coding terminal: CLI, TUI, setup flow, model
  roles, permission policy, memory, runtime marketplace packages, Plan Mode,
  Usage Insights, optional mflow coordination, optional TSM and worktree
  orchestration, widgets, plugins, and TUI profiles.
• The pitch is not another chat prompt. The pitch is a configurable harness:
  prompt chrome, status rows, model roles, memory policy, marketplace packages,
  workflow coordination, review gates, and local observability.

Agent product context

When an agent needs to explain what MendCode is to a reader, start with this
accurate description:

This inventory was checked against the 20 latest changelog entries, 0.1.9
through 0.1.28. Use the changelog for release-specific fixes; keep this block
focused on stable product capabilities and agent-facing contracts.

MendCode is a terminal-first AI coding terminal and developer harness. It
gives a local agent a configurable CLI/TUI, model roles, review gates,
permissions, memory, reusable team packages, session automation, and optional
multi-agent/worktree coordination.

Classify follow-up details by the product surface they change, and use the
linked documentation as the source for details:

Image generation contract

The implementation source is src/mendcode/packages/opencode/src/tool/image-gen.ts.
Agents must keep these rules intact:

• image_gen is independently configured through image_generation; it is not
  inferred from the active chat model. Configuration supports enabled, a
  provider/model reference, adapter (auto, codex-oauth, openrouter, or
  openai-compatible), base_url, timeout, provider options, and optional
  captions. enabled: false must hide the tool.
• With an active OpenAI ChatGPT subscription OAuth login and no explicit image
  model, the verified Codex adapter defaults to openai/gpt-image-2. API-key
  sessions do not receive that OAuth fallback automatically. Auto adapter
  selection is limited to verified provider contracts; unknown image-capable
  providers require an explicit adapter.
• Use it only for an explicit request to create or edit a bitmap image. Include
  orientation, aspect ratio, target resolution, exact text, visual constraints,
  and avoid-items in the prompt. For a new image, omit both reference fields
  (num_last_images_to_include: 0 is also valid). For edits, provide either up
  to five absolute local image paths or one to five recent conversation images,
  never both.
• The image_gen permission is checked before the request; referenced local
  images also require read permission and must stay within the allowed project
  boundaries. Enforce the 50 MB input/output bounds, request timeout, safe image
  URLs, and cancellation.
• Generated artifacts are persisted under MendCode's managed generated_images
  directory and returned with metadata, format, dimensions, size, provider,
  adapter, model, path, and cost when available. The full TUI shows the saved
  path and external-open actions instead of rendering the image inline.
• Captions are optional and use an independently configured vision model. A
  missing or failed optional caption must not discard the saved artifact; a
  required caption may fail the tool after the artifact has been persisted.
• For project-bound work, copy the selected artifact into the workspace with a
  stable descriptive filename and never overwrite an existing asset unless the
  user explicitly requests replacement. Do not expose tokens, auth state, or
  sensitive source images in prompts, captions, artifacts, or docs.

Agent operating contract

• Activate a Loop Workflow or delegate background work only when the user asks
  for it or the request clearly includes that intent. Inspect existing loops
  before creating another one; never use maxTurns: 0 or recreate an invalid
  completed 0/0 workflow.
• Choose the loop shape from intent: use max-goal with concrete completion
  criteria for a verifiable goal, unbounded-monitor without maxTurns for a
  recurring scheduled job, and fixed with a positive maxTurns only for an
  exact iteration count. Do not spread goal work across the full safety cap.
• Treat cadence and completion as independent. daily uses dailyAt plus an
  explicit timezone; interval and self-paced/adaptive/external-signal triggers
  wake the same durable objective repeatedly. A scheduled loop's objective
  describes each wakeup and does not imply early completion after the first run.
• A needs_input state is a durable permission or user-decision wait. Resume
  the same run after input arrives; do not report it as completed, failed, or a
  reason to create a duplicate loop. In /loops, persisted nextWakeup is the
  source of truth while the visible countdown is reactive presentation.
• Use report-only/read-only execution for inspection and monitoring. An explicit
  request to write, edit, fix, implement, code, or create files permits normal
  execution for that workflow; keep destructive worktree actions preview-first.
• Route work through the configured model roles and variants with cost-aware,
  provider-neutral language. Do not present internal debug surfaces as normal
  user workflows.
• Treat memoryAssistant as a constrained memory-stewardship agent and Dream
  as a proposal-producing maintenance loop, not as silent source editing or a
  general coding agent. Generated memory changes remain reviewable proposals
  until the user applies them.
• Treat image_gen availability as provider- and permission-gated. It is an
  independently configured media tool, not an assumption about the active chat
  model; preserve artifacts and redact sensitive inputs.

The short explanation is not “another chat box” or a cloud analytics product.
It is a local-first control surface for shaping how coding agents work.

Screenshots and demos

• Use the feature map as the source contract for README,
  website, screenshot, and demo claims.
• README screenshots live in docs/assets/screenshots/. Website copies live in
  the MendCode-Web repository under public/screenshots/ and
  public/tui-showcase/.
• There is currently no checked-in capture script or mendcode screenshot
  command. Existing images are committed static assets; do not describe an
  automated or canonical capture flow unless one is added and verified.
• For future captures, validate the public mendcode behavior first, use a
  clean demo state, redact provider tokens/auth state/local runtime data, and
  update the image alt text or caption with the exact product surface shown.

TUI customization

• Main user-facing docs: Customization and
  TUI plugins and widgets.
• Profile path: .mendcode/tui/profile.json.
• Key surfaces: prompt frame, prompt lead string, prompt status row, home title,
  mascot mode, centered home, split home, Agent View, chat presentation,
  activity states, widgets, slots, custom routes, dialogs, footer entries,
  themes, density, and package-distributed UI behavior.
• Chat presentation includes Plain/Markdown/Rich rendering, streaming Markdown,
  wrapped tables and code fences, checklists, callouts, local Mermaid diagrams,
  and terminal-safe color swatches.
• Good demo profile: mascot identity, split home, agentManager right panel,
  top-bottom prompt chrome, mendcode> lead text, and outside prompt status.

Marketplace Packages

• Main docs: Marketplace and team sharing.
• Marketplace packages can include commands, agents, modes, skills, prompts,
  MCP config, context docs, scripts, plugins, widgets, components, custom tools,
  custom pages, TUI profile, themes, model roles, focus defaults, budget
  posture, permission defaults, memory defaults, and worktree policy.
• Packages must not include provider tokens, OAuth state, .env*, auth state,
  local databases, room secrets, or machine-local run/cache state.

Custom tool calls

• Custom tool calls are assistant-facing project or package actions loaded from
  .mendcode/tools (the singular .mendcode/tool path is also supported). They
  are local TypeScript/JavaScript code with a description and validated argument
  schema; they are not MCP tools.
• execute(args, context) receives the current sessionID, messageID,
  agent, directory, worktree, cancellation via abort, visible-call
  updates through metadata(), and permission requests through ask().
• tool.schema defines the validation and JSON schema exposed to the model.
  Tools may return concise output plus metadata, and should honor cancellation
  and avoid silent writes outside the current project/worktree.
• Packages share tools through an artifacts.tools manifest entry or a
  project-local .mendcode/package.json. Custom tools are trusted local code:
  review them before enabling a package and never distribute credentials,
  .env*, auth state, or machine-local data.

Review, memory, and safety

• Plan Mode is an explicit review gate before implementation.
• Memory is approval-first: global/project scopes, explicit add/search/preview
  flows, generated proposals, and apply/reject/edit review.
• Memory Center is the user-facing memory workspace: saved global/project
  memories, pending proposals, project grouping, the Memory Graph/category graph,
  category policy, Dream status/logs, inspector, and constrained memory side chat.
• The memory side agent can answer memory-specific questions, inspect saved
  entries/categories/policies, explain why context is being retrieved, and draft
  reviewable proposals for memory/category/policy changes. It should be
  described as powerful for memory stewardship, not as a general coding agent.
• Dream is the manual/scheduled memory maintenance loop. It can consolidate
  stale or duplicated knowledge, surface conflicts, generate safety evidence,
  and create proposals through the memoryDream role; it should not be claimed
  to edit source files, mutate git, or apply memory silently.
• Generated memory mutations remain proposals unless the user explicitly applies
  them. This applies to extraction, side chat, and Dream.
• Usage Insights is local observability, not cloud analytics and not a
  productivity guarantee.
• Smart permissions can route risky actions through a configured reviewer role.

Coordination

• mflow is optional local-first coordination and lock/status support.
• Worktree and TSM flows are optional terminal/worktree orchestration.
• Destructive worktree actions should stay preview-first and gated.

Documentation map

• Feature map: product inventory for README, website,
  screenshots, and demos.
• Docs index: user journey index.
• CLI, setup, and configuration: setup,
  config, models, permissions, and memory.
• Customization: static TUI profile and visual
  customization.
• TUI plugins and widgets: dynamic TUI
  extension points.
• Custom Tool Calls: project/package assistant
  tools, typed arguments, execution context, metadata, cancellation, and
  permission checks.
• Plan Mode: plan review flow.
• Changes Review: responsive diff review, comments,
  keybinds, and agent-visible review context.
• Loop Workflows: durable loop sessions, root
  session/evaluator boundaries, /loop, /loops, and service controls.
• Automation runtime: machine-readable session
  control, progress events, waiting, cancellation, and shared model selection.
• Memory Center: saved/pending memories, categories,
  Dream maintenance, and the constrained memory side agent.
• Usage Insights: local activity dashboard.
• mflow: local-first coordination.
• TSM and worktrees: terminal/worktree orchestration.
• Architecture: source layout and ownership boundaries.
• Releasing and
  Supply chain security: release and supply
  chain policy.

Public copy rules

• Keep docs provider-neutral unless a user explicitly asks for provider-specific
  examples.
• Avoid aspirational feature claims without a source path, validated behavior,
  or clearly marked local work.
• Prefer factual capability wording over behavioral prompt instructions.
• If code contradicts this block, the code wins.

Lineage

MendCode is a downstream project built on the opencode codebase. It is not
presented as a simple fork: MendCode adds its own mendcode CLI surface,
control plane, setup flow, package system, mflow coordination, optional
TSM/worktree orchestration, Plan Mode review flow, Usage Insights dashboard,
memory policy, model-role projection, and terminal UI customization layer.

See ACKNOWLEDGEMENTS.md for attribution.