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