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