Files and paths

Sigil owns one directory and adds two lines elsewhere. Nothing else on your system is modified.

~/.sigil/

• Directory~/.sigil/

  • Directoryapp/ the git clone — this is the install

    • …
  • Directorybin/ stable launcher shims

    • sigil
    • sigil-mcp
  • config.json all configuration, chmod 600
  • CLAUDE.md instructions + hot-context snapshot
  • Directorydb/ the embedded database (PGlite mode only)

    • …
  • Directorysnapshots/

    • …
  • Directoryschemas/

    • …
  • identity.key Ed25519 secret for device pairing
  • Directoryiroh/ peer-to-peer transport state

    • …
  • gui.token dashboard auth token
  • sock daemon Unix socket
  • sigild.pid
  • sigild.log append-only daemon log
  • heartbeat.json
  • .hook-errors.log append-only diagnostic log
  • .last-clean-doctor
  • .update-available
  • .active-session.json
  • .stop-cursor.json
  • .stop-spool.jsonl
  • .hook-dedup.json
  • .spawn.lock
  • .daemon-breaker.json

The ones that matter

Path
app/	The git clone. sigil update fast-forwards it.
bin/	Stable shims. Every agent integration points here, never at a versioned path — which is what keeps memory working across Node version switches and reinstalls. sigil connect re-pins them.
config.json	Single source of truth for configuration. Sparse; defaults merge at read time. Contains API keys and database credentials. chmod 600.
CLAUDE.md	Sigil’s instructions plus the top-20 hot-context snapshot. Regenerated by sigil context.
db/	The embedded PGlite database, in embedded mode only. This is your memory in that mode.
identity.key	Ed25519 secret used for device pairing. Losing it means re-pairing every device.
.hook-errors.log	Append-only. sigil doctor reads it; five unacknowledged errors in 24h makes doctor exit non-zero.
sigild.log	Daemon log. sigil daemon logs --follow.

Daemon runtime files

sock, sigild.pid, heartbeat.json, .spawn.lock, .daemon-breaker.json — recreated on start. Safe to delete when the daemon is stopped.

.daemon-breaker.json is the circuit breaker that stops repeated spawn attempts after failures, rather than retrying forever.

Hook state

.active-session.json, .stop-cursor.json, .stop-spool.jsonl, .hook-dedup.json track which session is live, how far the Stop hook has read, spooled work not yet processed, and the content-hash dedup window for PostToolUse.

Deleting them loses in-flight capture, not stored memory.

---

~/.claude/

• Directory~/.claude/

  • CLAUDE.md one @import line added
  • settings.json four hook entries merged in

Sigil adds exactly one line to your CLAUDE.md:

@~/.sigil/CLAUDE.md

And merges four hook entries into settings.json — UserPromptSubmit, PostToolUse, Stop, SessionEnd. Your existing hooks and settings are preserved, not overwritten.

---

Other clients

Client	File
Codex CLI	~/.codex/config.toml (MCP entry) · ~/.codex/AGENTS.md (steering)
Cursor	~/.cursor/mcp.json
Kiro	~/.kiro/settings/mcp.json · ~/.kiro/steering/sigil.md
Continue	~/.continue/config.json
Cline	cline_mcp_settings.json in your VS Code user directory
Windsurf	~/.codeium/windsurf/mcp_config.json

sigil uninstall removes Sigil’s entries from these while preserving anything else in them.

---

Your shell rc

One line, added by the installer:

export PATH="$HOME/.sigil/bin:$PATH"

---

What holds secrets

Treat these as credentials

• ~/.sigil/config.json — API keys and the database connection string. It’s chmod 600; keep it that way, and keep it out of dotfile repos.
• ~/.sigil/identity.key — the Ed25519 secret for device pairing.
• ~/.sigil/gui.token — the dashboard bearer token.
• ~/.sigil/db/ — in embedded mode, your entire memory.

Facts themselves can also contain sensitive material. Secret masking runs at the ingest choke point, before embedding and storage, but it’s pattern-based defence in depth — not a guarantee.

---

What to back up

Priority	What
Essential	Your database — pg_dump, or ~/.sigil/db/ in embedded mode
Useful	config.json — saves re-running setup, but re-running setup is easy
Only for pairing	identity.key — without it, paired devices must re-pair

Everything else is derived or transient. See Backup and restore.

---

Where memory actually lives

Not in ~/.sigil/ unless you chose the embedded database. With Postgres, ~/.sigil/ holds only configuration, runtime state, and the hot-context snapshot — the memory itself is in your database.

---

Removing it all

rm -rf ~/.sigil

Removes the install, the config, and — in embedded mode — the data. Then:

• Delete the export PATH="$HOME/.sigil/bin:$PATH" line from your shell rc
• Remove the four Sigil hook entries from ~/.claude/settings.json
• Remove the @~/.sigil/CLAUDE.md line from ~/.claude/CLAUDE.md

Or let sigil uninstall do the client unwiring first. An external Postgres database and its sigil_app user survive; drop them yourself. See Uninstalling.