Workspace Structure
Understand the local .pulse folder Pulse AI creates in your project.
Why the workspace matters
Pulse AI is workspace-first. The project folder you open becomes the place Pulse AI reads from, writes to, and uses as evidence later.
That is why installation and initialization are separate steps. The extension can be installed globally, but each useful Pulse AI setup needs a local workspace with Pulse AI files inside it.
What Pulse AI creates
The .pulse folder is the local operating record. The most important areas are:
| Path | What it holds | Why it matters |
|---|---|---|
.pulse/actions/tasks | Board items and task lifecycle metadata | Scope, owner, dependencies, status, dispatch state, and review history live here. |
.pulse/knowledge | Research, deliverables, presentations, screenshots, notes, and narration artifacts | This is the durable evidence library for completed work. |
.pulse/config | Preferences, platform settings, billing or provider configuration, and output rules | These settings control how agents format work, dispatch, and generate narration. |
.pulse/dispatch | Context files sent to agents | Dispatch context explains what each worker was asked to do. |
.pulse/logs and runtime state files | Recent operational signals | These help diagnose stuck pools, reload behavior, and agent failures. |
How to inspect a healthy workspace
A healthy workspace has task files that match the visible board, Knowledge Items for completed research or deliverables, and preferences that match the way Pulse AI is behaving.
If the UI looks stale, inspect the files before creating duplicate tasks. The file record is often clearer than a cached panel after reloads or interrupted terminals.
What not to delete
Do not delete .pulse just to clear confusion. You may remove the board history, Knowledge Items, preferences, or proof future reviewers need.
If a folder was initialized by mistake, preserve anything useful first, then intentionally reinitialize the correct project folder.
Setup proof
Workspace setup is complete when:
.pulse/actions/taskscan hold board items..pulse/knowledgeexists for durable artifacts..pulse/config/preferences.jsonexists or can be created by Pulse AI.- Pulse AI opens the app shell for this folder.
- A small quickstart item can be dispatched or tracked without writing into the wrong project.
Having trouble with the local files? See Help Center: Workspace setup fails or .pulse is missing.