fedora-csb-system-manager
1#+title: Claude Code Infrastructure
2#+author: Vincent Demeester
3#+date: [2025-12-03 Wed]
4
5* Overview
6
7This directory contains Claude Code infrastructure that is shared across machines and tracked in git. It includes agents, skills, hooks, plugins, and settings for the Personal AI Infrastructure (PAI).
8
9Inspired by [[https://github.com/danielmiessler/Personal_AI_Infrastructure][Daniel Miessler's Personal AI Infrastructure]].
10
11* Directory Structure
12
13#+begin_src
14dots/.config/claude/
15├── README.org # This file
16├── agents/ # Specialized AI agents
17├── hooks/ # Event-driven automation hooks
18├── plugins/ # Custom plugins (session-manager, etc.)
19├── skills/ # Modular AI capabilities
20│ ├── CORE/ # Core operating principles
21│ │ ├── CONSTITUTION.md
22│ │ ├── SKILL.md
23│ │ ├── prompting.md
24│ │ └── history-system.md # History/notes integration
25│ ├── homelab/ # Homelab infrastructure management
26│ ├── golang/ # Go development best practices
27│ ├── nix/ # Nix/NixOS best practices
28│ └── notes/ # Note-writing workflow (denote)
29└── settings.json # Shared settings (tracked in git)
30
31~/.config/claude/
32├── agents/ -> /home/vincent/src/home/dots/.config/claude/agents/
33├── hooks/ -> /home/vincent/src/home/dots/.config/claude/hooks/
34├── plugins/ -> /home/vincent/src/home/dots/.config/claude/plugins/
35├── skills/ -> /home/vincent/src/home/dots/.config/claude/skills/
36├── settings.json -> /home/vincent/src/home/dots/.config/claude/settings.json
37├── settings.local.json # Machine/project-specific (NOT tracked)
38└── history/ # Captured sessions and logs (synced via Syncthing)
39 ├── sessions/ # Work session summaries
40 ├── learnings/ # Problem-solving insights
41 ├── research/ # Deep investigations
42 ├── execution/ # Command outputs
43 ├── decisions/ # Architecture decisions
44 └── tool-outputs/ # Captured tool executions (via hooks)
45
46~/.claude/ -> ~/.config/claude/ (backward compatibility)
47#+end_src
48
49**Note**: History entries in =~/.config/claude/history/= are interconnected with denote notes in =~/desktop/org/notes/= using the =:history:= tag. History is synced across machines via Syncthing.
50
51**Migration Note**: Claude Code now uses XDG Base Directory specification (=~/.config/claude/=). For backward compatibility, =~/.claude/= is symlinked to =~/.config/claude/= so older documentation and hooks continue to work.
52
53* Components
54
55** Agents (agents/)
56
57Specialized AI agents with specific expertise:
58- *engineer* - Software engineering and implementation
59- *architect* - Architecture and PRD creation
60- *designer* - UX/UI design and accessibility
61- *claude-researcher* - Web research with WebSearch
62- *researcher* - Comprehensive multi-tool research
63
64See =agents/= for individual agent documentation.
65
66** Skills (skills/)
67
68*** CORE Skills
69The CORE skills auto-load and define fundamental operating principles:
70- *CONSTITUTION.md*: Personal AI philosophy and architectural principles
71- *SKILL.md*: Core behaviors, response patterns, and workflows
72- *prompting.md*: Effective prompting guidelines
73- *history-system.md*: Integration between history capture and denote notes
74
75*** Domain-Specific Skills
76- *homelab*: Managing NixOS infrastructure in ~/src/home repository
77- *golang*: Go development patterns, testing, and Nix integration
78- *nix*: NixOS/home-manager configuration best practices
79- *notes*: Note-taking in denote format with org-mode
80- *Art*: Visual content generation and Mermaid diagrams
81- *Createskill*: Skill creation and validation
82
83See each skill's =SKILL.md= for documentation.
84
85** Hooks (hooks/)
86
87Event-driven automation implemented in Go (see =~/src/home/tools/claude-hooks=):
88- *claude-hooks-initialize-session* - SessionStart: Sets terminal title, logs session start
89- *claude-hooks-capture-tool-output* - PostToolUse: Logs tool executions to JSONL
90- *claude-hooks-save-session* - SessionEnd: Prompts to save session summary
91- *claude-hooks-validate-docs* - Manual/Pre-commit: Validates documentation links
92
93See =tools/claude-hooks/README.md= for detailed documentation.
94
95** Plugins (plugins/)
96
97Custom Claude Code plugins:
98- *session-manager*: Provides =/save-session= command for creating session summaries
99
100* Installation and Setup
101
102** Setup on New Machine
103
104To set up Claude Code infrastructure on a new machine:
105
106#+begin_src bash
107# Clone the home repository
108cd ~/src/home
109
110# Run make to create all symlinks
111cd dots
112make all
113
114# This will link:
115# - ~/.config/claude/skills/
116# - ~/.config/claude/agents/
117# - ~/.config/claude/hooks/
118# - ~/.config/claude/plugins/
119# - ~/.config/claude/settings.json
120# - ~/.claude/ -> ~/.config/claude/ (backward compatibility)
121
122# Optionally create machine-specific settings
123cat > ~/.config/claude/settings.local.json <<EOF
124{
125 "permissions": {
126 "allow": [
127 "Bash(*)"
128 ]
129 }
130}
131EOF
132#+end_src
133
134** Makefile Targets
135
136#+begin_src bash
137# Link individual components
138make claude-skills # Link skills
139make claude-agents # Link agents
140make claude-hooks # Link hooks
141make claude-plugins # Link plugins (session-manager, etc.)
142make claude-settings # Link settings.json
143
144# Link everything
145make all
146#+end_src
147
148* Settings Strategy
149
150** settings.json (Shared)
151
152*Location*: =dots/.config/claude/settings.json= (symlinked to =~/.config/claude/settings.json=)
153
154*Purpose*: Shared configuration across all machines
155
156*Contains*:
157- Hook configurations
158- Enabled plugins list
159- General preferences (alwaysThinkingEnabled, etc.)
160- Shared MCP server configs
161
162*Why shared*:
163- Consistent hooks across machines
164- Same plugins enabled everywhere
165- Synchronized preferences
166- Uses absolute paths that are consistent (=/home/vincent/.config/claude/...=)
167
168** settings.local.json (Machine-Specific)
169
170*Location*: =~/.config/claude/settings.local.json= or project =.claude/settings.local.json=
171
172*Purpose*: Machine or project-specific overrides
173
174*Contains*:
175- Permissions (project-specific)
176- Machine-specific paths
177- Local environment variables
178- Project-specific plugin configs
179
180*Not tracked in git*: Machine/project-specific configuration
181
182** Settings Precedence
183
184Claude Code merges settings in this order:
1851. =settings.json= (base configuration)
1862. =settings.local.json= (overrides)
187
188Local settings always take precedence over shared settings.
189
190** Permissions
191
192Permissions are intentionally kept in =settings.local.json= because:
193- Different projects need different permissions
194- Security policies may vary by machine
195- Easier to audit per-project permissions
196
197Example project-specific permissions:
198#+begin_src json
199{
200 "permissions": {
201 "allow": [
202 "Bash(make:*)",
203 "Bash(nix:*)",
204 "WebFetch(domain:docs.example.com)"
205 ]
206 }
207}
208#+end_src
209
210* Usage
211
212** Skills
213Skills are automatically available in Claude Code sessions. No special invocation needed - Claude will reference them contextually based on the task.
214
215** Editing Skills
216
217Skills are plain markdown files that can be edited directly:
218
219#+begin_src bash
220# Edit a skill
221cd ~/src/home/dots/.config/claude/skills
222vim homelab/SKILL.md
223
224# Changes are immediately available (no rebuild required)
225#+end_src
226
227** Adding New Skills
228
2291. Create a new directory in =.config/claude/skills/=
2302. Add a =SKILL.md= file with the skill content
2313. Skills are automatically discovered by Claude Code
232
233Example:
234#+begin_src bash
235mkdir -p .config/claude/skills/rust
236cat > .config/claude/skills/rust/SKILL.md << 'EOF'
237# Rust Development Skill
238
239## Purpose
240Guide Rust development following best practices.
241
242## Best Practices
243- Use cargo for builds
244- Write comprehensive tests
245- Follow Rust idioms
246EOF
247#+end_src
248
249* History System
250
251The History system automatically captures and documents AI interactions to build a comprehensive knowledge base.
252
253Adapted from the [[https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/.claude/skills/CORE/CONSTITUTION.md#history-system][Personal AI Infrastructure History System]].
254
255** Purpose
256Capture ALL valuable work for future reference, learning, and analysis.
257
258** Directory Structure
259
260#+begin_src
261~/.config/claude/history/
262├── raw-outputs/ # Raw event logs (JSONL)
263│ └── YYYY-MM/
264│ └── YYYY-MM-DD_all-events.jsonl
265│
266├── learnings/ # Problem-solving narratives
267│ └── YYYY-MM/
268│ └── YYYY-MM-DD-HHMMSS_LEARNING_description.md
269│
270├── sessions/ # Work logs and summaries
271│ └── YYYY-MM/
272│ └── YYYY-MM-DD-HHMMSS_SESSION_description.md
273│
274├── research/ # Analysis and investigations
275│ └── YYYY-MM-DD_topic/
276│ ├── analysis.md
277│ ├── findings.md
278│ └── sources.md
279│
280├── execution/ # Command outputs and results
281│ └── YYYY-MM/
282│ └── YYYY-MM-DD-HHMMSS_command-name.txt
283│
284└── upgrades/ # Architectural changes
285 ├── deprecated/
286 │ └── YYYY-MM-DD_upgrade-name/
287 │ ├── README.md
288 │ └── [deprecated files]
289 └── YYYY-MM-DD_upgrade-description.md
290#+end_src
291
292** What Gets Captured
293
294*** Automatic Capture (via hooks)
295- Session start and completion events
296- Tool usage and command execution
297- All events logged to =raw-outputs/YYYY-MM/YYYY-MM-DD_all-events.jsonl=
298
299*** Manual Capture (by AI)
300- *Research completed* → save to =research/=
301- *Learning captured* → save to =learnings/=
302- *Work summary* → save to =sessions/=
303- *Command outputs* → save to =execution/=
304
305*** Workflow-Driven
306- Some skills auto-save outputs
307- Example: research skill → =history/research/=
308
309** Categories
310
311*** Learnings
312Problem-solving narratives and insights:
313- How a bug was diagnosed and fixed
314- Why a particular approach was chosen
315- Lessons learned from failures
316- Pattern discoveries
317
318Example: =2025-12/2025-12-03-154500_LEARNING_wireguard-vpn-setup.md=
319
320*** Sessions
321Work logs and summaries of significant work sessions:
322- What was accomplished
323- Decisions made
324- Next steps
325- Context for future reference
326
327Example: =2025-12/2025-12-03-100000_SESSION_homelab-infrastructure-upgrade.md=
328
329*** Research
330Analysis and investigations:
331- Technical explorations
332- Tool evaluations
333- Architecture comparisons
334- Deep dives into topics
335
336Example: =2025-12-03_personal-ai-infrastructure/=
337
338*** Execution
339Command outputs and results:
340- Build logs
341- Test results
342- Deployment outputs
343- Script executions
344
345Example: =2025-12/2025-12-03-150000_nixos-rebuild.txt=
346
347*** Upgrades
348Architectural changes and migrations:
349- System improvements
350- Breaking changes
351- Deprecated approaches
352- Migration guides
353
354Example: =2025-12-03_claude-skills-implementation.md=
355
356** Scratchpad vs History
357
358*** Scratchpad (=~/.config/claude/scratchpad/=)
359- Temporary working files
360- Tests and experiments
361- Draft outputs
362- Delete when done
363
364*** History (=~/.config/claude/history/=)
365- Permanent valuable outputs
366- Research findings
367- Learnings and insights
368- Session logs
369- Keep forever
370
371** Critical Rule
372*When in doubt, save to history!*
373
374** Benefits
375
3761. *Learn from history*: Reference past solutions to similar problems
3772. *Track evolution*: See how approaches and understanding develop over time
3783. *Share knowledge*: Documentation is automatically created
3794. *Context building*: AI can reference past interactions for better assistance
3805. *Institutional memory*: Build a knowledge base over time
381
382** Integration with Denote Notes
383
384The History system is interconnected with the denote note-taking system in =~/desktop/org/notes/=.
385
386*** Tag-Based Integration
387All history-related notes use the =:history:= tag plus category-specific tags:
388- =:history:session:= - Work session summaries
389- =:history:learning:= - Problem-solving insights
390- =:history:research:= - Deep investigations
391- =:history:decision:= - Architecture decisions
392- =:history:execution:= - Command execution logs
393
394*** Bidirectional Links
395History entries in =~/.config/claude/history/= and denote notes cross-reference each other:
396
397From history to notes (markdown links in .md files):
398#+begin_src markdown
399## Related Notes
400- [Topic Note](~/desktop/org/notes/20251203T151822--topic__history_session.org)
401#+end_src
402
403From notes to history (org-mode links in .org files):
404#+begin_src org
405,* Related History
406- [[file:~/.config/claude/history/sessions/2025-12/2025-12-03-150000_SESSION_implementation.md][Implementation Session]]
407#+end_src
408
409**Note on formats**: History uses markdown (=.md=), notes use org-mode (=.org=). Both are plain text, searchable, and git-friendly. Use appropriate link syntax for each format.
410
411*** Finding History-Linked Notes
412#+begin_src bash
413# All history notes (by tag)
414ls ~/desktop/org/notes/*__history*.org
415
416# Automated history notes (by pkai signature)
417ls ~/desktop/org/notes/*==pkai*.org
418
419# Specific category
420ls ~/desktop/org/notes/*__history_learning*.org
421ls ~/desktop/org/notes/*==pkai*__history_session*.org
422
423# Search across both systems
424rg "topic" ~/.config/claude/history/ ~/desktop/org/notes/*__history*.org
425#+end_src
426
427*Signature*: =pkai= stands for "Personal Knowledge Automated Infrastructure" and identifies notes created by the history system. This makes it easy to distinguish automated notes from manual ones.
428
429*** When to Use Each System
430- *History directory* (=~/.config/claude/history/=): Chronological tracking, raw captures, session-by-session
431- *Denote notes* (=~/desktop/org/notes/=): Topic-based organization, long-term reference, knowledge building
432- *Both*: Significant learnings, important decisions, research worth sharing
433
434See =skills/CORE/history-system.md= for complete integration details.
435
436** Implementation Status
437
438Current implementation (manual workflow):
4391. Manually create history entries for significant work
4402. Manually create denote notes with =:history:= tag
4413. Cross-link between history and notes
4424. Organize by category and date
443
444Future automation (with hooks):
445- Automatic session capture via hooks
446- Auto-suggest history entries for significant work
447- Searchable indexing across both systems
448- AI-assisted note generation from history
449
450* Philosophy
451
452** Deterministic Over Probabilistic
453Prefer structured, testable, code-based solutions over pure prompt engineering.
454
455** Progressive Disclosure
456Load context in three tiers:
4571. *Essential*: Core principles always loaded
4582. *Contextual*: Task-specific knowledge loaded as needed
4593. *Reference*: Detailed docs retrieved on demand
460
461** Code Before Prompts
462Build CLI tools and code first, then wrap with AI assistance. Code is:
463- Testable
464- Versioned
465- Deterministic
466- Shareable
467
468* Version Control
469
470Skills are tracked in the home repository:
471
472#+begin_src bash
473cd ~/src/home
474git add dots/.config/claude/
475git commit -m "feat: Update Claude AI skills"
476#+end_src
477
478* References
479
480- [[https://github.com/danielmiessler/Personal_AI_Infrastructure][Personal AI Infrastructure]] - Original inspiration
481- [[file:~/src/home/CLAUDE.md][Repository CLAUDE.md]] - Repository-specific Claude instructions
482- [[file:~/desktop/org/notes/20251203T151822--personal-ai-infrastructure-implementation-plan__ai_claude_infrastructure_nixos_plan.org][PAI Implementation Plan]] - Planning notes
483
484* Benefits of This Approach
485
4861. *Consistency*: Same agents, skills, hooks, and plugins everywhere
4872. *Version Control*: Infrastructure tracked in git
4883. *Flexibility*: Machine-specific overrides when needed
4894. *Portability*: Easy to set up on new machines
4905. *Maintainability*: Single source of truth for shared config
4916. *Instant updates*: Edit skills, changes are immediate
4927. *No rebuilds*: No NixOS rebuild required (for skills/agents/plugins)
4938. *Iterative*: Easy to refine and experiment
494
495* Troubleshooting
496
497** Symlinks not working?
498#+begin_src bash
499cd ~/src/home/dots
500make all
501#+end_src
502
503** Settings not loading?
504#+begin_src bash
505# Check symlink
506ls -la ~/.config/claude/settings.json
507
508# Should point to: /home/vincent/src/home/dots/.config/claude/settings.json
509
510# Check backward compatibility symlink
511ls -la ~/.claude
512# Should point to: ~/.config/claude
513#+end_src
514
515** Hooks not running?
516#+begin_src bash
517# Check settings.json has hooks configured
518cat ~/.config/claude/settings.json | grep -A 10 hooks
519
520# Verify hook binaries are in PATH
521which claude-hooks-initialize-session
522which claude-hooks-capture-tool-output
523which claude-hooks-save-session
524#+end_src
525
526** History not syncing?
527#+begin_src bash
528# Verify Syncthing is running
529systemctl --user status syncthing
530
531# Check if claude-history folder is configured
532# After rebuilding NixOS with updated globals.nix
533#+end_src
534
535* Related Documentation
536
537- *Agents*: See individual agent =.md= files in =agents/=
538- *Skills*: See each skill's =SKILL.md= in =skills/=
539- *Hooks*: See =~/src/home/tools/claude-hooks/README.md=
540- *History System*: See =skills/CORE/history-system.md=
541- *Repository Instructions*: See =~/src/home/CLAUDE.md=
542- *PAI Implementation Plan*: See =~/desktop/org/notes/20251203T151822--personal-ai-infrastructure-implementation-plan__ai_claude_infrastructure_nixos_plan.org=