claude-code/docs/plans/2024-12-29-pa-agent-mode-design.md

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:

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:

# 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:

{
  "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):

{
  "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)