Project workspace
A project is more than its terminals. 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 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 |
| Antigravity CLI | GEMINI.md | ~/.gemini/GEMINI.md |
Skills are discovered under .agents/skills,
.codex/skills,
.claude/skills, and
.gemini/antigravity-cli/skills, both in
the project and under your home directory. 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. Push and pull controls appear only when an upstream has commits to move. They run as Quick Runs, so the full Git output stays visible without taking the current terminal away from its agent. Git state refreshes after those commands finish.
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-terminal menu to
create a fresh branch from HEAD and open a
terminal 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 terminals, 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 terminal, 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 terminal that owns it, or to the closed terminal
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 terminal 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 terminals covers the menu,
panes, monitors, scratchpad, previews, and persistence.
Commands, startups, and jobs covers the
committed files under .saggar.