Pyra/CLAUDE.md

Pyra — Developer Guide

What Is This

Pyra is a personal AI assistant CLI combining a multi-provider AI chat interface with an automation/skills system (Stage 2+) and an encrypted vault (Stage 3+).

Project Roadmap

Stage 1 — Core CLI (current)

Working pyra executable with provider setup wizard, streaming chat REPL, .md-based memory in ~/.pyra/memory/, and hard security boundaries around the vault.

Stage 2 — Skills / Automations

Shell (.sh), PowerShell (.ps1), and Python (.py) scripts in ~/.pyra/skills/. The AI can suggest running a skill, but execution requires explicit user approval (y/n prompt). No skill can access the vault. Skills are discovered by the pyra CLI, not by the AI.

Stage 3 — Vault Encryption

Encrypt ~/.pyra/vault/secrets/ using age (or GPG fallback). Pyra decrypts in memory at call time only — no plaintext ever written to disk after initial setup. Secret rotation support. Per-key passphrases optional.

Stage 4 — Security Audit Sub-agent

A separate pyra security audit command that spins up a sandboxed AI agent whose sole job is scanning for vulnerabilities: prompt injection in memory files, unexpected vault access attempts in security.log, outdated dependency CVEs, permission drift on ~/.pyra/. Report written to ~/.pyra/security_audit.md (not AI-readable during normal chat).

Stage 5 — Web UI / Advanced Features

Optional local web interface (FastAPI + HTMX or similar). Embedding-based memory search (ChromaDB or sqlite-vec). Scheduled automations via cron-style skill scheduling. Multi-profile support (work vs personal).

---

Architecture

Source: src/pyra/

Module	Purpose
cli.py	Click entrypoint. Subcommands: setup, chat, memory
setup/providers.py	Provider registry — pure data, no I/O
setup/wizard.py	questionary-based interactive setup wizard
config/schema.py	Pydantic v2 models — no API keys, only provider_id/model/base_url
config/manager.py	ruamel.yaml round-trip config read/write, chmod 600 enforced
config/dirs.py	bootstrap() — creates ~/.pyra/ tree, checks vault sentinel every startup
chat/session.py	prompt_toolkit REPL loop, slash commands, calls vault reader inline
chat/renderer.py	Live streaming markdown via rich, injection warning panel, key redaction
chat/history.py	Conversation list, token budget trimming, system prompt construction
memory/reader.py	list_memories(), read_memory(), load_context_for_session()
memory/writer.py	write_memory(), append_memory() — relative names only, no traversal
memory/index.py	Auto-regenerate MEMORY_INDEX.md on every write
vault/reader.py	get_key(provider_id) — sole accessor of vault/secrets/api_keys.json
vault/writer.py	set_key(), delete_key() — only called from setup wizard
security/boundaries.py	assert_safe_path(), check_vault_lock(), BLOCKED_PREFIXES
security/injection.py	scan_response() — 15 regex patterns, 4 categories, logs to security.log
utils/paths.py	pyra_home(), ensure_dir(), safe_chmod(), expand()

Runtime: ~/.pyra/

~/.pyra/
├── config.yaml          chmod 600  ← provider_id, model, base_url ONLY
├── security.log         chmod 600  ← injection event log
├── memory/              chmod 700
│   ├── user/profile.md
│   ├── context/
│   ├── knowledge/
│   └── MEMORY_INDEX.md
├── skills/              chmod 700  ← Stage 2
│   ├── bash/
│   ├── powershell/
│   └── python/
└── vault/               chmod 700  ← AI CANNOT ACCESS
    ├── .vault_lock      chmod 400  ← sentinel; missing = refuse to start
    └── secrets/
        └── api_keys.json  chmod 400  ← ALL API keys

---

Security Rules (never break these)

1. Never pass config file contents into a system prompt — config may reveal provider/model
2. Never bypass assert_safe_path() — not even in tests (use tmp_pyra_home fixture instead)
3. Always chmod 600/400 after writing any file in ~/.pyra/
4. No shell execution from AI-generated text — ever (Stage 2 uses explicit approval gates)
5. vault/reader.py and vault/writer.py are the only modules that import from pyra.vault
6. API key retrieved inline at call time — never stored as an instance variable or logged

Adding a New Provider

Edit src/pyra/setup/providers.py. Add a new Provider dataclass entry with all required fields. litellm handles dispatch automatically via the litellm_prefix field. Add a test in tests/unit/test_providers.py to verify the new entry.

Installing for Development

uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
pyra setup

Or with pip:

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pyra setup

Running Tests

pytest tests/ -v                           # all unit + security tests
pytest tests/integration/test_lmstudio.py  # requires LM Studio at localhost:1234

Commit Convention

feat(module): short description
fix(module): short description
test: description
docs: description
chore: description