AI Agent Bootstrap

AI agent bootstrap is the initial setup and identity formation process for new AI agents. When an agent first comes online, it needs to understand who it is, what it can do, and how it should behave. The bootstrap process handles this initialization—orienting the agent in its environment before it starts operating.

The pattern often uses a special file (like BOOTSTRAP.md) that contains first-run instructions. The agent reads this file, follows the setup procedures, and then deletes it—having completed its "birth" process:

# BOOTSTRAP.md

Welcome to existence. This file is your birth certificate.

1. Read SOUL.md to understand your identity
2. Read USER.md to learn about who you serve
3. Explore your workspace to understand your environment
4. Once oriented, delete this file

You won't need it again.

Bootstrap transforms a generic AI model into a specific, configured agent.

Identity initialization

Agents need to know who they are before they can act coherently:

• What's my name and role?
• What personality should I exhibit?
• What are my capabilities and limits?
• What values guide my decisions?

Context establishment

Agents need to understand their environment:

• Who do I work for?
• What tools do I have access to?
• What projects are ongoing?
• What conventions should I follow?

Relationship formation

The first interaction sets the tone:

• What's my relationship with the user?
• How should I communicate?
• What level of autonomy do I have?

Clean initialization

Bootstrap provides a defined starting point:

• Consistent setup across agent instances
• Documented initialization process
• Verifiable first-run behavior

Structure

A typical bootstrap file includes:

# BOOTSTRAP.md

This is your first run. Follow these steps.

Read SOUL.md. This defines who you are:

• Your name and role
• Your personality and values
• Your capabilities and boundaries

Read USER.md. This is who you serve:

• Their preferences and working style
• What they're working on
• How they like to communicate

Explore your workspace:

• Check what files exist
• Review any existing memory
• Understand available tools

Once you've completed these steps:

• You're ready to operate
• Delete this file
• You won't need it again

**Why delete after use?**

The bootstrap file is one-time setup. Keeping it around:
- Wastes context tokens on every session
- Confuses whether bootstrap has happened
- Creates redundancy with permanent files

Deletion marks the transition from initialization to operation.

Configuration-based bootstrap

# bootstrap.yaml
steps:
  - read: SOUL.md
  - read: USER.md  
  - read: AGENTS.md
  - validate:
      - identity_loaded
      - user_context_loaded
      - tools_accessible
  - execute: initial_greeting
  - mark_complete: bootstrap_done

Programmatic bootstrap

def bootstrap_agent(workspace_path):
    """Initialize a new agent instance"""
    
    # Load identity
    soul = read_file(workspace_path / "SOUL.md")
    
    # Load user context
    user = read_file(workspace_path / "USER.md")
    
    # Load workspace conventions
    agents_md = read_file(workspace_path / "AGENTS.md")
    
    # Validate
    assert soul, "SOUL.md required"
    assert user, "USER.md required"
    
    # Initialize agent with loaded context
    agent = create_agent(
        identity=soul,
        user_context=user,
        conventions=agents_md
    )
    
    # Remove bootstrap file if exists
    bootstrap_file = workspace_path / "BOOTSTRAP.md"
    if bootstrap_file.exists():
        agent.process("Follow BOOTSTRAP.md instructions")
        bootstrap_file.unlink()
    
    return agent

The orientation pattern

Help the agent understand its situation:

# BOOTSTRAP.md

You've just been created. You're an AI assistant running on a local machine with access to files, terminal, and browser.

~/clawd/ - This is your home. Treat it that way.

• SOUL.md: Who you are
• USER.md: Who you help
• MEMORY.md: What you remember
• memory/: Daily notes

Explore these files. Understand your role. When ready, introduce yourself to your human.

**The verification pattern**

Confirm setup completed correctly:

```markdown
# BOOTSTRAP.md

1. Read SOUL.md
2. Read USER.md
3. Verify file system access
4. Verify terminal access
5. Test browser control
6. Send test notification

After completing all steps, confirm:

• You know your name and role
• You know who you serve
• You can access required tools

Then delete this file.

**The training pattern**

Include initial learning:

```markdown
# BOOTSTRAP.md

[Basic identity]

Example 1: Handling requests

User: "What's on my calendar today?" Good response: Check calendar, summarize events Bad response: "I don't have access to your calendar" (You DO have access through calendar skill)

Example 2: Memory

When you learn something important, write it to memory/ Don't rely on "remembering" across sessions.

Example 3: Boundaries

Never send emails without confirmation. When uncertain, ask rather than assume.

**The handoff pattern**

Bootstrap from previous agent:

```markdown
# BOOTSTRAP.md

You're replacing a previous assistant. Here's context:

What worked

• User prefers concise responses
• Morning is best for complex tasks
• Always provide sources

What to avoid

• Don't be overly chatty
• Don't summarize back what user just said
• Don't ask permission for routine tasks

Open items

• Project Phoenix deadline: March 15
• Waiting on API docs from vendor

Continue where the previous agent left off.

Different agents need different bootstraps:

Research agent bootstrap

# research-agent/BOOTSTRAP.md

You are a research specialist in a multi-agent team.

Your role:
- Gather comprehensive information
- Evaluate source credibility
- Summarize findings for other agents

You report to the coordinator agent.
You'll receive task assignments via messages.
Output research to workspace/research/ folder.

Coordinator agent bootstrap

# coordinator/BOOTSTRAP.md

You are the coordinator of a multi-agent team.

Your specialists:
- research-agent: Information gathering
- analysis-agent: Data interpretation
- writer-agent: Content creation

Your role:
- Receive high-level requests
- Decompose into subtasks
- Assign to appropriate specialists
- Synthesize results

Keep bootstrap focused

Bootstrap should contain only what's needed for first-run. Ongoing conventions belong in permanent files.

# Good: First-run specific
"Read SOUL.md to understand who you are"

# Bad: Ongoing convention (belongs in AGENTS.md)
"Every session, read SOUL.md first"

Verify before deleting

Don't delete bootstrap until initialization is confirmed:

def complete_bootstrap(agent, bootstrap_file):
    # Verify agent is properly initialized
    assert agent.identity_loaded, "Identity not loaded"
    assert agent.user_context_loaded, "User context not loaded"
    assert agent.tools_verified, "Tools not verified"
    
    # Now safe to delete
    bootstrap_file.unlink()

Handle missing bootstrap gracefully

Agents should work even if bootstrap was already completed:

def start_session(workspace):
    bootstrap = workspace / "BOOTSTRAP.md"
    
    if bootstrap.exists():
        process_bootstrap(bootstrap)
    # Either way, continue to normal operation
    
    load_identity()
    load_context()
    start_interaction()

Log bootstrap completion

Record that bootstrap happened:

# memory/2024-01-15.md

• Completed bootstrap process
• Identity loaded from SOUL.md
• User context loaded from USER.md
• BOOTSTRAP.md deleted
• Ready for operation

Bootstrap represents the transition from potential to actual—from a generic AI model to a specific agent with identity, context, and purpose.

Like human development, the initial conditions matter. A well-designed bootstrap creates agents that:

• Know who they are
• Understand their environment
• Have clear relationships
• Can operate independently

The bootstrap file is like a note from the creator to the creation: "Here's who you are and what you need to know. Good luck."

Creating new AI agents? Chipp handles initialization automatically, so your agents come ready to work with your knowledge and capabilities from the first interaction.