How to use pm7Code

pm7Code does not ship its own model. You pick a coding agent per topic, and pm7Code is the workspace around it. Six native agents are supported, and you can switch between them or hand a running session over to a different one at any time. New topics default to pm7 unless you pick another agent.

The right sidebar sits next to the workspace and shows one of three panes, chosen from the header: the Assistant — a full CView and Command Center bound to a single window-tab — the Browser (BView), or Files. The header groups the choice: Assistant with General, Project, and Topic sub-modes, plus separate Browser and Files buttons. Only one pane is visible at a time; the others stay mounted so their state survives when you switch.

The Assistant is not a seventh native agent. It is an ordinary topic session parked in its own column so you can keep a helper conversation open while you work in the main view.

pm7Code needs every agent to behave consistently — to ask questions the same way, hand off Git the same way, and respect the same conventions. It does this by injecting its own protocol into each agent through that agent's native system-prompt channel, built once when the agent starts.

Three words come back everywhere in pm7Code, and the difference between them decides when a prompt is sent. Read this section once and the rest of the prompt documentation falls into place.

pm7Code does not treat every prompt field as the same thing. Some prompts describe stable behavior, some describe the current project, some describe the topic you are working on, and some are temporary instructions for one turn.

The practical result is simple: the first message of a session carries the inherited context down to and including the Topic prompt, and every message after that stays lean — what you typed plus the Every message prompt.

Each layer inherits from the layer above it. When a lower layer enables an override, that value becomes the effective prompt for everything below it. If the override is enabled but left empty, that prompt is intentionally disabled for that branch.

A session opens with startup context and then stays lean. The first message carries System, Group, Project, and Topic; every message after that is just what you typed plus the Every message prompt.

Group, Project, and Topic settings all have a Prompts tab. Each tab shows the prompt layers that make sense at that level. Project and Topic prompts are plain .mdfiles under the project's Folder — see Prompts live in your repo — in pm7-Code/<Project-UUID>/. There is no separate Home folder setting; only Folder remains in Project settings. If the Folder is unreachable, the window reports that the prompt files could not be read, or shows “Loading from the Project folder…” while it tries.

Project and Topic prompts are not stored inside pm7Code once a project has a Folder. They are plain .mdfiles under the project's Folder, in pm7-Code/<Project-UUID>/, so they are versioned, reviewed, and shared through git like any other file. The settings windows read and write exactly those files.

<Project folder>/pm7-Code/
  <Project-UUID>/
    Project-prompt.md      the project layer
    System-override.md     project overrides the System prompt
    Group-override.md      project overrides the Group prompt
    System-Copy.md         generated reference copy, overwritten
    Group-Copy.md          generated reference copy, overwritten
    <Topic-UUID>/
      Topic-prompt.md          the topic layer
      Every-Message-prompt.md  sent with every message
      System-override.md       topic overrides System
      Group-override.md        topic overrides Group
      Project-override.md      topic overrides Project

The two *-Copy.md files are different from the rest: pm7Code writes them but never reads them. They exist so you can see in the repo which System and Group prompt apply to this project — the source of truth is the app itself. They are refreshed when the app starts and when a prompt changes, so they can briefly lag behind. Editing them is pointless: every edit is overwritten.

When an agent needs a decision from you, it does not bury the question in a wall of text. pm7Code renders a structured question card with numbered options and an always-present free-text field, right inside the transcript. You answer in the workspace and the agent continues from your choice.

Neighbor-agent review is an optional per-topic setting. When it is on, the active agent consults a designated buddy agent before asking you a question, and presents both recommendations so you can decide with a second opinion in front of you.

When the agent is in the middle of a turn, pressing the Escape key while the Command Center input has focus stops the active turn. This is the same action as the Stop current turn button in the CView title bar.

The Projects search field supports qualifiers when you want to narrow the sidebar before applying normal text search. Use this when a word appears in many projects but you only want results from one exact project, group, or topic.

The filter bar and Show menu also include a Push to master squeeze — see Push dots and filter.

At the end of a coding turn, an agent can emit a fenced GitServiceRequest block. pm7Code detects that block in the conversation, creates a visible Git Service card, and enqueues a background Git job in the main process.

The important detail is that the request is asynchronous from the user's point of view. Once pm7Code has accepted the request, the agent is free to continue with testing, inspection, or the next task while commit and push run separately.

A GitServiceRequest appears as a dedicated card in CView. The card shows the job state, the repository path, the files included in the request, and any error returned by the Git Service.

The Git Service is intentionally strict. It is designed to commit exactly the files from the finished turn and to stop when the repository state no longer matches the request.

Most users do not need to write this block by hand. pm7Code's agent protocol emits it automatically at the end of a turn when files changed. Advanced users and agent authors can use this shape:

```GitServiceRequest
{
  "cwd": "/Users/patrickmast/Dev/pm7-code",
  "files": [
    "site/app/docs/page.tsx",
    "site/app/page.tsx"
  ],
  "scope": "docs",
  "commitMessage": "docs: document Git Service"
}
```

pm7Code keeps its own memory of durable facts, preferences, and conventions. Because the memory belongs to pm7Code and not to any one agent, it works the same whether you are running Claude Code, Codex, Pi, Cursor, or Grok — it is not tied to a single agent's own memory store.

It mirrors the Git Service model: the agent only proposes a memory write, and pm7Code is the authority that decides what is actually stored. A proposal shows up as a Memory card in CView with its own status, just like a Git Service card.

A skill is a small, reusable instruction pack that teaches an agent how to do a recurring job the way you want it done — how you deploy, how you sign a macOS build, how you write a release note. It follows the open Agent Skills standard: a plain SKILL.md file with a name and a description, optionally alongside supporting scripts and assets.

The problem skills usually create is duplication. Every agent keeps its own copy, so the same skill has to be written and maintained several times. Copies drift apart, and you end up tied to whichever agent happens to hold the good version. pm7Code removes that entirely: it keeps one canonical store and shares it with every agent automatically, so a skill written once works the same across all of them.

The same mechanism covers three kinds of instruction pack: skills (used by every agent), plus guides and commands for the agents that understand those concepts. And it no longer stops at one machine: your set lives in your account and follows you to every machine and server you run agents on — see Available everywhere below, and Under the hood for what it does on disk.

Beyond the terminal, the prompt, and the agent transcript, pm7Code adds a few panels that keep the rest of the dev loop in the same window.

Connections heal themselves. Switching networks — wifi to 5G, a hotspot, a VPN coming back — removes the old path without telling either side, so a socket can keep reporting that it is open long after nothing gets through. pm7Code therefore does not trust appearances: every connection is checked with a heartbeat. A dead one is spotted within about half a minute, and right away when you return to the window. Agent sessions reattach and replay what you missed; the terminal opens a fresh connection. Nothing to reload.

Writing sessions can work in their own git worktree instead of editing the project checkout directly. That keeps parallel sessions from stepping on each other, and landing back onto the base branch is an explicit step in CView.

On the WebApp, an App Theme is a named profile that bundles the full look and layout of one device: the active color theme, fonts, visual style, panel visibility, and sidebar and Assistant column open state and width. The macOS desktop app does not use App Themes — there, account settings remain the source.

Each device remembers its own active theme. The theme definitions sync with your account, so the same profiles are available on every WebApp device you use. There is always one active theme; a Default theme is created from your current look the first time you need it.

Settings → General has a Settings Backup section where you point pm7Code at a private Git repository. Every export saves your settings to your account first, so the backup always matches what you see in Settings, then commits and pushes every setting, prompt, memory, skill, and theme to that repo.

pm7codeis a one-shot, scriptable entrypoint that ships with pm7Code. Give it a prompt and it runs a single turn, prints the agent's final answer to stdout, and exits — the same shape as claude -p, but through the pm7Code motor. Pass the prompt as an argument or pipe it on stdin.

# One-shot against the local motor (auto-started if needed)
pm7code "summarize what changed in this repo"

# Pipe the prompt via stdin, run it through Codex
echo "write a haiku about pty buffers" | pm7code --agent codex

When you point it at a loopback address and nothing is listening yet, the CLI starts a local motor for you and reuses it on the next call. Pointed at a remote address, it never spawns anything — it only connects.

# Machine-readable output for scripts/CI: NDJSON events + a final result line
pm7code --json --agent claude "list the open TODOs"

# Continue the most recent session in this folder, then resume an exact one
pm7code --continue "now add tests for it"
pm7code --resume <pm7SessionId> "follow up on that"

# Talk to a remote motor over your tailnet (paired device + opt-in full-auto)
pm7code --server ws://100.x.y.z:8787 \
        --device-id "$PM7CODE_DEVICE_ID" \
        --device-key "$PM7CODE_DEVICE_KEY" \
        --full-auto "deploy the site"

A failed job means pm7Code deliberately stopped before completing the commit or push. Use the card message as the source of truth and send a fresh request after fixing the cause.