Settings
import { Aside } from ‘@astrojs/starlight/components’;
Ptah has a two-layer settings model that keeps personal preferences portable while letting each project override the bits that matter for that project.
The two layers
Section titled “The two layers”| Layer | Location | Purpose |
|---|---|---|
| Global | ~/.ptah/settings.json | User-wide preferences — provider API keys, default model, theme, MCP port |
| Workspace | <workspace>/.claude/ and <workspace>/.ptah/ | Per-project agents, plugins, templates, and overrides |
Workspace settings win when both layers define the same key. This matches how VS Code, Git, and most modern editors resolve configuration.
Where to edit
Section titled “Where to edit”- Open Settings from the left-hand rail (or press
Ctrl+,/Cmd+,). - Most options can be edited through the UI.
- Power users can edit
~/.ptah/settings.jsondirectly — changes are picked up on the next launch.
What’s in this section
Section titled “What’s in this section”- Global settings — the full schema of
~/.ptah/settings.json, including provider API keys - Workspace settings — how
.claude/and.ptah/shape per-project behavior - Theme — light/dark and accent color
- API keys — how to obtain credentials for each provider
- Autopilot — autonomous execution toggles
- Import & export — backup and restore your configuration
- Why not package.json? — rationale for storing provider settings outside
package.json