Add PA Agent Mode design document
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 <noreply@anthropic.com>
This commit is contained in:
OpenCode Test
189
docs/plans/2024-12-29-pa-agent-mode-design.md
Normal file
189
docs/plans/2024-12-29-pa-agent-mode-design.md
Normal file
@@ -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)
|
||||
Reference in New Issue
Block a user