Wiki
Reference for the parts of PounceCode that are worth knowing about before you need them.
Profiles
A profile is a provider, an endpoint, a model and the settings that go with them. You can have as many as you like and switch between them inside a conversation — useful for drafting a plan on a strong model and running the steps on a cheap or local one.
| Provider | Notes |
|---|---|
| Anthropic | Native API. Reports cache usage and rate-limit reset headers. |
| OpenAI | Native API, and the shape most gateways imitate. |
| Google Gemini | Native API preferred — it reports the real context window per model. |
| Ollama | Local. The endpoint reports its own context length. See the local guide. |
| OpenAI-compatible | vLLM, LM Studio, corporate gateways, anything speaking the same shape. |
Where credentials live
API keys are not stored in the config file. The config holds a reference of the form keyring:<profile>:<field> and the value lives in an encrypted store beside it. One consequence worth knowing: the reference is keyed by profile name, so renaming a profile by hand-editing the config will orphan its credential and the endpoint will answer 401. Rename through the app instead.
The working folder
The folder shown on the status bar is where relative reads and writes actually land, where git runs, and where shell commands execute. Click it to change it; the model is told immediately when it changes.
One place, for everything
Reads, writes, git and the shell all resolve against the same folder. They used to disagree — writes used the work folder and reads used the process directory — which produced the memorable failure of a model writing a file, failing to read it back, and giving up.
Documents go to a subfolder
Exported documents land in artifacts/ inside the work folder, so a generated report does not sit in the middle of your source tree. Source files the model writes go to the work folder itself.
Projects
A project groups conversations and carries rules that are given to the model every time it works there. If the folder contains an AGENTS.md, that is read and honoured — conventions, the test command, things not to touch.
This is the cheapest available lever on output quality. "Tests live beside the code they cover" and "run python3 -m pytest, not pytest" in a file the model always sees will save more rounds than any amount of prompting per request.
Viewers and editing
Files open inside the app rather than handing you off to another program.
Text
Syntax highlighting in the current theme, with optional line numbers. Editable in place.
Markdown
Rendered and source views, both editable, switchable by tab.
Saving
Unsaved changes are flagged before you navigate away. If the file changed on disk while you were editing it — likely, when an agent is working in the same tree — you are offered both versions rather than one silently winning.
The pounce CLI
Installed alongside the app. Same engine, same profiles, same tools, same config — in a terminal, and in a pipe.
--yes answers confirmations automatically, for unattended use. Think about what that means with the dangerous tools before you reach for it in a script.
Document export
The model can hand back a finished document rather than a wall of chat: Markdown, PDF, DOCX or HTML, written into artifacts/. The same renderer produces the app's own documentation, deliberately — an export regression shows up in our work before it shows up in yours.
Driving the app over MCP
PounceCode can expose a driver surface over MCP on loopback — start a conversation, set the work folder, switch profile, send a turn, read the task board and the transcript. It is off by default and you turn it on explicitly.
This exists because the interesting bugs are in the seams between components, and those only appear when something drives the real application rather than a mock. It is also how the benchmark suite runs: scenarios against a live app, where every check reads the disk or runs a subprocess instead of reading the model's reply.
Privacy
No accounts, no telemetry, no analytics. Conversations are stored locally in SQLite. The only thing that leaves your machine is what you send to the model provider you configured — and if that provider is running on your own hardware, nothing leaves at all.
PHI mode
A stricter mode for regulated data: web tools are disabled entirely and tool calls are audited to a local log.
Confirmations
Dangerous tools ask before running, and shell confirmation can be required for every command. While a plan is held for review, writes are refused outright.
Troubleshooting
| Symptom | Cause |
|---|---|
| 401 from a local or gateway endpoint | A credential reference that no longer resolves — usually a profile renamed outside the app. Re-enter the key in Settings. |
| Model forgets things mid-task | Context window too small. On Ollama this is nearly always the 4096 default; see the local guide. |
| Files appear somewhere unexpected | Check the working folder on the status bar — that is where writes land, whatever the conversation's project says. |
ctx shows a dash | The window could not be determined. It is learned from the first overflow error. |
| Repeated rate limiting | The provider's limit is lower than the work needs. PounceCode paces itself and recovers, but a tight quota will still be a tight quota. |
| A turn ends with nothing said | Report it. A turn that produces neither text nor a tool call is a bug, and the app is supposed to say so rather than fall silent. |