Claude Code CLI Boot Sequence

Documentation of files loaded during Claude Code initialization on linuxserver.lan

Legend

Loaded at Boot
NOT Loaded (Gap)
On-Demand (Agent Invocation)
Parent File
Child/Referenced File

Auto-Loaded from ~/.claude/ (Built-in Behavior)

Claude Code automatically scans and loads these files from ~/.claude/ at startup:

File/Directory Auto-Loaded Purpose
~/.claude/settings.json YES Global configuration (permissions, hooks, MCP servers)
~/.claude/CLAUDE.md YES User-level memory/context (imports agent-docs, skills)
~/.claude/agents/*.md METADATA Agent definitions - names/descriptions at boot, full content on invoke
~/.claude/skills/*/SKILL.md METADATA Skill definitions - names/descriptions at boot, full content on invoke
~/.claude/commands/*.md YES Slash commands - available immediately when typing /
~/.claude/docs/** NO Subdirectory CLAUDE.md files NOT auto-loaded

Note: ~/.claude/CLAUDE.md imports subdirectory files via @.claude/docs/... syntax, allowing hierarchical organization while maintaining auto-loading.

Visual Boot Sequence Tree

BOOT START │ ├─[0] ~/.claude/settings.json (Global Settings - Auto-loaded) │ ├─[0.5] ~/.claude/CLAUDE.md (User Memory - Auto-loaded) │ │ │ ├─@.claude/docs/agent-docs/CLAUDE.md (PM Agent Context) │ │ │ ├─@.claude/docs/agent-docs/inter-agent-protocol.md (Inter-Agent Protocol) │ │ │ └─@.claude/skills/CLAUDE.md (User Skills Summary) │ ├─[1] $HOME/projects/CLAUDE.md (Project Root - Auto-loaded) │ │ │ ├─[2] @home/projects/.claude/docs/agent-docs/CLAUDE.md (Specialist Agents) │ │ │ ├─[3] @home/projects/.claude/skills/CLAUDE.md (Project Skills Summary) │ │ │ ├─[4] @home/projects/AINotes/SYSTEM-OVERVIEW.md (System Overview) │ │ │ └─[5] @home/projects/AINotes/directives.md (User Directives) │ ├─AINotes On-Demand: network.md, security.md, logging.md (via skills) │ ├─Agents: 4 discovered (pm, architect, developer, security) │ ├─Skills: 15 discovered (7 user + 8 project) │ └─Commands: 6 slash commands available

Detailed Boot Sequence

Phase 1: Infrastructure Root (Auto-loaded by Claude Code)

1
$HOME/projects/CLAUDE.md
LOADED
Infrastructure-wide context. Auto-loaded for any project under /home/administrator/projects/
↓

Phase 2: Agent Context (Referenced from CLAUDE.md)

2
$HOME/.claude/docs/agent-docs/CLAUDE.md
LOADED
PM Agent context - role, responsibilities, when to invoke specialist agents
3
$HOME/.claude/docs/agent-docs/inter-agent-protocol.md
LOADED
Shared inter-agent communication protocol (workspaces, escalation, file patterns)
↓

Phase 3: AINotes Infrastructure Documentation

4
$HOME/projects/AINotes/SYSTEM-OVERVIEW.md
LOADED
Current infrastructure state (62 containers, services, architecture)
5
$HOME/projects/AINotes/directives.md
LOADED
User directives - skill/agent invocation rules, secrets management, naming

Phase 4: On-Demand Reference Documentation (via Skills)

$HOME/projects/AINotes/network.md
ON-DEMAND
Network topology, DNS, Docker networks - loaded by network-config, troubleshooting, service-deployment skills
$HOME/projects/AINotes/security.md
ON-DEMAND
Security policies, Keycloak SSO, OAuth2 - loaded by keycloak-setup, secrets-security, traefik-setup skills
$HOME/projects/AINotes/logging.md
ON-DEMAND
Observability stack configuration - loaded by logging-observability skill

Design Decisions

Progressive Disclosure Pattern

The boot sequence follows Anthropic's progressive disclosure pattern:

  • Boot: Load minimal essential context (SYSTEM-OVERVIEW, directives)
  • On-Demand: Load detailed reference docs when skills are invoked
  • Result: Faster boot, smaller initial context, relevant info when needed

On-Demand Reference Files

These AINotes files are loaded by their respective skills, not at boot:

File Loaded By Skills
network.md network-config, troubleshooting, service-deployment
security.md keycloak-setup, secrets-security, traefik-setup
logging.md logging-observability

On-Demand Loading (Not at Boot)

Agent Definitions (Loaded when agent invoked via Task tool)

Agent Definition File Reads Context From
PM $HOME/.claude/agents/pm.md $HOME/.claude/docs/agent-docs/CLAUDE.md
Architect $HOME/projects/.claude/agents/architect.md $HOME/projects/.claude/docs/agent-docs/CLAUDE.md
Developer $HOME/projects/.claude/agents/developer.md $HOME/projects/.claude/docs/agent-docs/CLAUDE.md
Security $HOME/projects/.claude/agents/security.md $HOME/projects/.claude/docs/agent-docs/CLAUDE.md

Skills (Loaded when skill invoked via Skill tool)

Location Skills Load Pattern
$HOME/.claude/skills/ naming-validator, secrets-security, skill-creator, gitlab-integration, architecture-diagram-creator Metadata at boot, full SKILL.md on invocation
$HOME/projects/.claude/skills/ service-deployment, keycloak-setup, traefik-setup, postgres-integration, network-config, logging-observability, troubleshooting, nginx-static-site Metadata at boot, full SKILL.md on invocation

File Reference Matrix

File References / Imports Boot Status
~/.claude/CLAUDE.md → @.claude/docs/agent-docs/CLAUDE.md
→ @.claude/docs/agent-docs/inter-agent-protocol.md
→ @.claude/skills/CLAUDE.md 		USER ROOT
$HOME/projects/CLAUDE.md → @home/projects/.claude/docs/agent-docs/CLAUDE.md
→ @home/projects/.claude/skills/CLAUDE.md
→ @home/projects/AINotes/SYSTEM-OVERVIEW.md
→ @home/projects/AINotes/directives.md 		PROJECT ROOT
$HOME/.claude/docs/agent-docs/CLAUDE.md PM Agent context (references inter-agent-protocol.md) LOADED
$HOME/projects/.claude/docs/agent-docs/CLAUDE.md Specialist Agents (Architect, Developer, Security) LOADED
$HOME/projects/AINotes/SYSTEM-OVERVIEW.md Infrastructure state (62 containers, architecture) LOADED
$HOME/projects/AINotes/directives.md User directives, invocation rules LOADED
$HOME/projects/AINotes/network.md Network topology, DNS, Docker networks ON-DEMAND
$HOME/projects/AINotes/security.md Security policies, Keycloak, OAuth2 ON-DEMAND
$HOME/projects/AINotes/logging.md Observability stack configuration ON-DEMAND

Additional Working Directories

What are "Additional Working Directories"?

These are configured via CLI, not files in ~/.claude/:

  • CLI flag: claude --add-dir /path/to/dir
  • Slash command: /add-dir /path/to/dir
  • settings.json: "additionalWorkingDirectories": ["/path"]
Configured Path Status Notes
/home/administrator/.claude/agent-docs STALE Old path - moved to .claude/docs/agent-docs/
/home/administrator/projects/.claude/docs/agent-docs EXISTS Contains specialist agents CLAUDE.md
/home/administrator/.claude/docs EXISTS Parent of agent-docs
/home/administrator/.claude/agents EXISTS Contains pm.md agent definition

Known Issue: CLAUDE.md files in additional working directories may NOT auto-load (documented bug).

Boot Statistics

Category At Boot On-Demand
CLAUDE.md Files 2 (user + project root) Per-project CLAUDE.md
Agent Context Files 3 (PM, Specialist, Protocol) Full agent definitions
Skill Summaries 2 (user + project) Full SKILL.md content
AINotes Files 2 (SYSTEM-OVERVIEW, directives) 3 (network, security, logging)
Agents Discovered 4 (pm, architect, developer, security) Full content on invoke
Skills Discovered 15 (7 user + 8 project) Full content on invoke
Commands Available 6 slash commands -