Project workspace
A project is more than its sessions. Saggar keeps the repository's documentation, agent instructions, skills, Git state, worktrees, and listening processes close enough to inspect without breaking focus.
Documentation
The Docs tab recursively lists Markdown and MDX files
from the project's documentation folder and renders the selected page
with a section outline. Its ＋ creates a new document, including nested
folders when you enter a path such as
guides/setup.md; it never replaces an
existing file. README.md and
index.md sort first, then the rest follow
their paths, so a nested documentation set stays recognizable.
The default folder is docs. Change it in
the project's Settings tab when a repository uses another relative
folder. The path cannot escape the project. An empty setting returns to
the default.
Agent context
The Agent context tab shows the instructions and skills that supported agents may load while working in this project. It combines project files with global files from your home directory, labels each one by scope and provider, and saves edits back to the file itself. This is the place to answer “what did the agent read?” without searching several hidden directories.
| Provider | Project instructions | Global instructions |
|---|---|---|
| Codex | AGENTS.md | ~/.codex/AGENTS.md |
| Claude Code | CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md | ~/.claude/CLAUDE.md |
| GitHub Copilot CLI | .github/copilot-instructions.md | ~/.copilot/copilot-instructions.md |
| Antigravity CLI | GEMINI.md | ~/.gemini/GEMINI.md |
| Pi | — | ~/.pi/agent/AGENTS.md |
| OpenCode | — | ~/.config/opencode/AGENTS.md |
Skills are discovered in the project under
.agents/skills,
.claude/skills,
.pi/skills,
.opencode/skills, and
.github/skills, and under
your home directory in .agents/skills,
.claude/skills,
.pi/agent/skills,
.config/opencode/skills,
.copilot/skills, and
.gemini/config/skills. Only files
already on disk appear. The separate
Saggar skill installer writes the user-level
copy only after you ask it to.
Git state and actions
Branch, dirty-file, ahead, and behind counts appear on projects, worktrees, and sessions. The counts use Git's locally stored upstream reference; choose Fetch to check for remote changes without changing working files. An unavailable comparison is shown explicitly. Push and pull run as quick runs, with Git's progress and refusals visible without taking the current session away from its agent. Git state refreshes after those commands finish.
The controls allow one sync operation per checkout at a time. Its progress appears wherever that checkout is shown, and the last result stays visible afterward. Click the indicator to see output while its terminal is available. Push follows the checkout's Git configuration, including any separate push remote. Pull is fast-forward-only and leaves Git's refusal visible if the branches have diverged. Fetch and pull remain available when the locally known counts are zero.
A project or worktree menu can open its checkout in the configured
editor, reveal it in Finder, copy its path, or open its remote on
GitHub. ⌘⇧G opens the current checkout on
GitHub directly. A missing or non-GitHub remote simply leaves that
action unavailable.
Worktrees
Choose In a new worktree… from the new-session menu to
create a fresh branch from HEAD and open a
session or agent there. Saggar places the checkout beside the main
repository as repo-branch, flattening
slashes in the branch name for the folder. Each checkout keeps its own
Git state and can open sessions, Finder, the editor, or GitHub from its
row.
Manage worktrees handles one checkout at a time. Review cleanup… scans every project and measures all extra worktrees before offering a batch. A checkout is selectable only when it has a branch, is clean, is not used by a live Saggar session, and has seen no file activity for seven days. Recent, dirty, detached, and in-use checkouts remain visible with the reason they are protected.
Removal uses git worktree remove, and Git
gets the final refusal. The branch stays. The checkout directory goes,
including ignored files inside it, so Saggar shows the measured size,
requires explicit selection, and asks once more before removing a
reviewed batch.
Ports
⌘⇧P opens the ports panel and immediately
scans listening processes started by Saggar. Each row ties a port and
PID back to the live session that owns it, or to the closed session
that left it behind. A URL reported by a monitor appears beside the
kernel's port and can be opened or copied.
A live owner offers Go there. A process left behind by a closed session offers a two-press Release action. Processes Saggar did not start are identified but never killed, and processes owned by other macOS users are outside the panel's view. The timestamp in the header says how fresh the scan is.
Related workflows
Projects and sessions covers the menu,
panes, monitors, scratchpad, previews, and persistence.
Commands, startups, and scheduled tasks covers their
files under .saggar.