From b1bf13caa81e69c31f815585adf8c8e48b96215a Mon Sep 17 00:00:00 2001 From: OpenCode Test Date: Mon, 29 Dec 2025 02:01:13 -0800 Subject: [PATCH] Add PA Agent Mode design document MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Design for persistent Claude Code environment with: - tmux session management (pa-mode script) - Hyprland keybind (Super+Shift+C) - Custom history storage with JSONL - Structured memory system (decisions, preferences, projects, facts) - Manual + hook-based summarization 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- docs/plans/2024-12-29-pa-agent-mode-design.md | 189 ++++++++++++++++++ 1 file changed, 189 insertions(+) create mode 100644 docs/plans/2024-12-29-pa-agent-mode-design.md diff --git a/docs/plans/2024-12-29-pa-agent-mode-design.md b/docs/plans/2024-12-29-pa-agent-mode-design.md new file mode 100644 index 0000000..ab95a7e --- /dev/null +++ b/docs/plans/2024-12-29-pa-agent-mode-design.md @@ -0,0 +1,189 @@ +# PA Agent Mode Design + +**Date:** 2024-12-29 +**Status:** Approved + +## Overview + +PA Agent Mode is a persistent Claude Code environment running in a dedicated tmux session with full autonomy and long-term memory. It provides an always-on personal assistant that maintains context across sessions through structured memory and journaled history. + +## Architecture + +``` +┌─────────────────────────────────────────────────────────┐ +│ PA Agent Mode │ +├─────────────────────────────────────────────────────────┤ +│ Launch Methods │ +│ ├── pa-mode (shell command) │ +│ └── Super+Shift+C (Hyprland keybind) │ +├─────────────────────────────────────────────────────────┤ +│ Runtime │ +│ ├── tmux session: "pa" │ +│ ├── Terminal: Alacritty │ +│ └── claude --dangerously-skip-permissions │ +│ --agent personal-assistant │ +├─────────────────────────────────────────────────────────┤ +│ Memory Layer │ +│ ├── history/ (raw JSONL per session) │ +│ ├── memory/ (structured summaries by category) │ +│ └── index.json (session metadata for search) │ +└─────────────────────────────────────────────────────────┘ +``` + +## Components + +### Launch Script (`pa-mode`) + +Location: `~/.claude/automation/pa-mode` + +**Usage:** +```bash +pa-mode # Attach to existing session, or create new one +pa-mode new # Force new session (archives current if exists) +pa-mode kill # Terminate the PA session +``` + +**Behavior:** +- Session exists + attached elsewhere → Attach (takes over) +- Session exists + detached → Attach +- No session → Create new session with: + - Working directory: `~` (home) + - Session name: `pa` + - Command: `claude --dangerously-skip-permissions --agent personal-assistant` + - History file: timestamped JSONL in history directory + +### Hyprland Keybind + +Added to Hyprland config: +```conf +# PA Agent Mode - Super+Shift+C +bind = SUPER SHIFT, C, exec, alacritty -e /home/will/.claude/automation/pa-mode +``` + +Behavior: Always opens a new Alacritty terminal attached to the PA tmux session. Multiple presses create multiple terminals viewing the same session. + +### History Storage + +Location: `~/.claude/state/personal-assistant/history/` + +**Structure:** +``` +history/ +├── 2024-12-29_01-30-00.jsonl # Raw conversation log +├── 2024-12-29_14-22-00.jsonl +└── index.json # Session metadata +``` + +**index.json schema:** +```json +{ + "sessions": [ + { + "id": "2024-12-29_01-30-00", + "started": "2024-12-29T01:30:00Z", + "ended": "2024-12-29T03:45:00Z", + "summarized": true, + "topics": ["k8s deployment", "fish shell config"] + } + ] +} +``` + +### Memory System + +Location: `~/.claude/state/personal-assistant/memory/` + +**Structure:** +``` +memory/ +├── decisions.json # Choices made, rationale recorded +├── preferences.json # User preferences learned over time +├── projects.json # Active/recent project context +├── facts.json # Factual knowledge about environment +└── meta.json # Last updated timestamps, stats +``` + +**Category file schema (example - decisions.json):** +```json +{ + "items": [ + { + "id": "uuid", + "date": "2024-12-29", + "decision": "Use JSONL for PA history instead of SQLite", + "rationale": "Simpler, human-readable, git-friendly", + "session": "2024-12-29_01-30-00" + } + ] +} +``` + +**On startup, PA reads:** +1. `general-instructions.json` (existing - explicit user instructions) +2. `memory/*.json` (all category files - learned context) + +### Summarization + +**Manual trigger:** +User types `/pa --summarize` or "summarize this session". PA: +1. Reviews current session conversation +2. Extracts items into appropriate category files +3. Marks session as summarized in `index.json` + +**End-of-session hook:** +When detaching from tmux or claude-code exits: +1. `pa-summarize` script intercepts exit +2. Sends summarization prompt to claude-code +3. PA extracts and writes to memory files +4. Session ends cleanly + +**Crash recovery:** +On next startup, PA checks for unsummarized sessions and offers to review them. + +## File Inventory + +### Files to Create + +| File | Purpose | +|------|---------| +| `~/.claude/automation/pa-mode` | Main launch script | +| `~/.claude/automation/pa-summarize` | Summary extraction script | +| `~/.claude/state/personal-assistant/history/index.json` | Session metadata index | +| `~/.claude/state/personal-assistant/memory/decisions.json` | Decision log | +| `~/.claude/state/personal-assistant/memory/preferences.json` | Learned preferences | +| `~/.claude/state/personal-assistant/memory/projects.json` | Project context | +| `~/.claude/state/personal-assistant/memory/facts.json` | Environment facts | +| `~/.claude/state/personal-assistant/memory/meta.json` | Memory system metadata | + +### Files to Modify + +| File | Change | +|------|--------| +| `~/.config/hypr/hyprland.conf` | Add Super+Shift+C keybind | +| `~/.claude/agents/personal-assistant.md` | Add memory loading to initialization | + +## Session Persistence + +- **Model:** Single persistent tmux session named "pa" +- **Crash handling:** Manual restart required +- **Reboot handling:** Session lost, recreate manually +- **No auto-restart:** Keeps complexity low + +## Design Decisions + +| Decision | Rationale | +|----------|-----------| +| Custom history storage over native claude-code history | Full control, dedicated location, easier indexing | +| JSONL format for history | Human-readable, git-friendly, append-only friendly | +| Structured memory categories | Selective loading, organized context | +| Manual + hook summarization | User control with automatic safety net | +| Full yolo mode | Trust PA completely, maximum efficiency | +| Simple tmux persistence | Avoid systemd complexity, manual restart acceptable | + +## Out of Scope (YAGNI) + +- Auto-restart on crash +- Systemd service for reboot persistence +- SQLite or database storage +- Periodic background summarization +- Toggle keybind behavior (focus/hide existing terminal)