Getting started
Podcode is one server and three ways to talk to it. The desktop app bundles the server and the web UI together; podcode web opens the same UI in your browser; podcode tui gives you a full terminal client. Whichever you use, the same sessions, the same memory, and the same configuration are behind it.
The pieces
| Piece | What it is |
|---|---|
| Workspace | A directory you've registered. Each one has its own sessions, file watcher, git context, and memory database. |
| Session | One conversation, with one transcript and one run-lock. Stop cancels whatever it is doing. |
| Agent | The system prompt, tool set, and permission rules the session is currently running under. You pick one per session, and it can change mid-session. |
| Harness | A named chain of agents that runs across one session, handing off from stage to stage. |
| Provider | Where the models come from — a cloud API, a local server, or a GPU endpoint Podcode deployed for you. |
Where things live
Two directories, resolved per-OS. The macOS and Linux forms are shown; on Windows the config directory is %APPDATA%\podcode and the data directory is %LOCALAPPDATA%\podcode\data — split deliberately, because a roaming profile must not carry the SQLite database.
| What | Where |
|---|---|
| Global config | ~/.config/podcode/config.json |
| Workspace config | .podcode/config.json in the workspace |
| Credentials | ~/.config/podcode/auth.json, encrypted at rest |
| Data (models cache, database, KV) | ~/.config/podcode/data/ |
| Memory database | .podcode/data/memory.db, per workspace |
| Shareable memory | .podcode/memory/, git-trackable JSON |
| Custom agents | ~/.config/podcode/agent/<id>.md |
| Skills | .podcode/skills/<name>/SKILL.md, or the same path under the config dir |
Almost everything in these docs is a key in one of the two config files. Every one of them also has a form in Settings that writes the same key, so you rarely have to open the file — but the file is the contract, and it is what these pages show.
Where to go next
- Terminal CLI — install the
podcodecommand and what it can do. - Permissions — what the agent may do without asking you.
- Configuration — the config layers and how they merge.
- Agents — the personas, and how to write your own.
- Harnesses — chaining agents into a pipeline.