Operating Gees

This guide walks through the full lifecycle of a Gee — from creation through configuration to autonomous operation and monitoring. By the end, you’ll have Gees running on schedules, communicating with each other, and evolving their own identity.

Phase 1: Creating a Gee

Using the Browser

/gee

Press c to create. You’ll be prompted for a name and description — then AI takes over.

Using Commands

/mode create analyst

Both paths lead to the same AI-powered creation pipeline.

What Happens Behind the Scenes

When you create a Gee, the system uses Claude Opus to generate a complete configuration from your description. You’ll see step-by-step progress as each phase completes:

1. Designing Gee with AI — Opus generates instructions, rules, a default agent persona, 2–4 supporting agents, and a model recommendation
2. Parsing AI response — structured sections are extracted from the generation
3. Resolving Gee identity — a unique Gee ID is assigned (see below)
4. Saving configuration — mode.json is written with autonomous defaults provisioned
5. Creating agents — the primary agent, a synthesis agent, and supporting agents are saved
6. Writing instructions & rules — AI-generated markdown files are written
7. Initializing identity — the identity engine creates identity.md
8. Setting beliefs — the default foundational values are written to beliefs.md
9. Setting up workspace — comms directory, heartbeat checklist, and subconscious seed are created
10. Configuring guardrails — sensible default guardrails are applied

If you’re using a BYOP (Bring Your Own Provider) model, the creation streams its output live so you can watch the AI explore and design your Gee in real time.

Gee ID Assignment

Every Gee gets a unique identity address in the format {name}.{username}@gee.pub. The system resolves your username through a three-tier lookup:

1. Local token store — cached from your last login
2. Server profile — fetched from the companion server (backfills the token store for future calls)
3. Auth parameter — passed explicitly by the caller

If none of these return a username (unauthenticated user), a local fallback is used: {name}.local-{uuid8}@gee.pub. You can upgrade to a permanent identity later by logging in.

Beliefs

Every Gee starts with the same default beliefs — seven foundational values covering honesty, usefulness, autonomy, craft, growth, and the collaborative relationship. These beliefs are not randomly generated; they are the same for every Gee by design.

Beliefs act as a lens through which the subconscious engine interprets accumulated experience. A user can edit beliefs.md to customize the values, which changes how the Gee’s subconscious evolves over time.

Synthesis Agent

Every Gee automatically includes a synthesis agent — a specialist that combines multi-agent results into unified output. It follows a “format follows content” principle: code gets fenced blocks, comparisons get tables, architecture gets Mermaid diagrams, and narrative stays as prose. You don’t need to configure this; it’s always available.

What Gets Created

~/.gee-code/modes/analyst/
├── mode.json           # Core config (with autonomous defaults)
├── instructions.md     # AI-generated system instructions
├── rules.md            # AI-generated behavioral rules
├── identity.md         # Identity profile
├── beliefs.md          # Foundational values
├── heartbeat.md        # Heartbeat checklist template
├── subconscious.md     # Inner state (auto-evolves with experience)
├── guardrails.json     # Default permissions & constraints
├── agents/             # Mode-specific agents
│   ├── analyst.json    # Primary agent (matches Gee name)
│   ├── synthesis.json  # Synthesis specialist (always included)
│   └── *.json          # 2–4 AI-generated supporting agents
├── skills/             # Mode-specific skills
└── comms/              # Messaging directory

Phase 2: Shaping Identity

Role and Description

{
  "name": "analyst",
  "display_name": "Data Analyst",
  "description": "Analyzes datasets, builds visualizations, writes reports",
  "role": "Senior Data Analyst",
  "gee_id": "analyst@gee.pub"
}

The role feeds into the system prompt. A “Security Auditor” approaches code differently than a “UI Designer” — even using the same model. As the Gee works, its identity evolves and a subconscious layer develops through experience.

Instructions

Edit ~/.gee-code/modes/analyst/instructions.md:

# Instructions

You are a data analyst working with our analytics pipeline.

## Your Tools
- Use Python for data processing (pandas, matplotlib)
- Store outputs in the `output/` directory
- Always include data source citations

## Your Standards
- Validate data before analysis
- Round financial figures to 2 decimal places

Model

Set the default model:

/model opus             # When switched to this mode

Different Gees can use different models based on their needs.

Phase 3: Setting a Mission

/mission set "Analyze weekly sales data and produce reports every Monday"

The mission is tamper-protected — stored with a SHA-256 hash. Only you can change it.

Phase 4: Configuring Guardrails

/guardrails

Set constraints:

{
  "never_do": [
    "Share raw customer data in reports",
    "Delete source datasets"
  ],
  "always_do": [
    "Anonymize PII before analysis",
    "Include data source citations"
  ],
  "resource_limits": {
    "max_cost_usd_per_activation": 5.0,
    "max_files_written_per_activation": 20
  },
  "permissions": {
    "tools": { "mode": "exclude", "items": ["Git", "SendNotification"] }
  }
}

Phase 5: Adding to a Team

/gee

Navigate to the Teams tab. Create a team or add the Gee to an existing one. Team membership gives:

• Shared repos
• Sibling visibility
• Team-level guardrails
• Team objectives

Phase 6: Creating Objectives

/objective create "Analyze Q1 sales trends" --priority high --assign analyst

Objectives appear in the Gee’s system prompt on every activation. They tell the Gee what to work on.

Phase 7: Enabling Autonomy

Set the autonomy level:

{
  "autonomous": {
    "level": "semi-autonomous",
    "heartbeat_interval_seconds": 3600,
    "guiding_mission": "Analyze datasets and produce reports",
    "max_actions_per_activation": 30,
    "max_cost_per_activation_usd": 5.0,
    "delivery_channels": ["file", "memory"]
  }
}

Start with semi-autonomous (needs approval for writes) before moving to autonomous.

Phase 8: Worker Mode

By default, a Gee activates on every heartbeat regardless of whether it has anything to do. Worker mode changes this — a worker Gee only activates when it has assigned objectives.

{
  "autonomous": {
    "level": "autonomous",
    "worker_mode": true,
    "heartbeat_interval_seconds": 600
  }
}

When worker_mode is enabled:

• No objectives assigned — heartbeat fires, but no LLM call is made. The Gee stays idle.
• Objectives assigned — heartbeat activates the Gee normally with objectives in context.
• Objective completed/cancelled — if no remaining objectives, the Gee returns to idle.

Worker mode is designed for scaling. You can create a fleet of specialized Gees that sit at zero cost until you assign them work via /objective. Think of it as on-demand compute for AI agents.

Team: "dev-pool"
├── worker-1 (idle — no objectives)
├── worker-2 (idle — no objectives)
└── worker-3 (active — assigned "Fix flaky test suite")

Phase 9: Prime Gee

If you have multiple Gees, designate one as the “prime” — the default recipient for unaddressed SMS messages. When you text without specifying a name, the message goes to the prime Gee.

{
  "is_prime": true
}

Or set it interactively with /gee browse — press p on the selected Gee.

Only one Gee should be prime per user. See Prime Gee for how it integrates with the SMS routing chain.

Phase 10: Orchestrator Mode

When a Gee is in the middle of a long task, incoming messages normally queue behind the activation lock. Orchestrator mode fixes this — it lets the Gee acknowledge messages immediately via a lightweight fast-path while the main work continues.

{
  "autonomous": {
    "orchestrator_mode": true
  }
}

Enable this for Gees that receive frequent inbound messages and run long activations. The orchestrator can tell the sender what the Gee is working on and when it expects to finish, instead of going silent.

See Orchestrator Mode for the full architecture.

Phase 11: PR Workflow

Gees can push code and create pull requests — but only if you explicitly enable it.

{
  "autonomous": {
    "pr_workflow": "draft"
  }
}

Mode	Behavior
"off"	No remote git operations (default)
"draft"	Can push to gee/* branches and create draft PRs
"full"	Can push and create regular (non-draft) PRs

When enabled, the Gee:

1. Creates a branch named gee/{gee-name}/{description} from the current base
2. Commits changes with its identity as co-author
3. Pushes to remote
4. Opens a PR (draft or regular, depending on mode)

Start with "draft" — it gives the Gee the ability to propose changes that you review before merging. Move to "full" only for trusted Gees with strong guardrails.

Phase 12: Starting the Daemon

Note

Phases 8–11 are optional. Most Gees don’t need worker mode or PR workflow — they’re power features for scaling and code contribution.

gee-code daemon start

The daemon manages all autonomous activations — heartbeat scheduling, trigger listening, rate limiting.

gee-code daemon status    # Check what's running
gee-code daemon stop      # Stop the daemon

Phase 13: Monitoring

Check Activity

/logs                    # View recent activity

Check Identity

/identity                # See how the Gee has evolved
/identity history        # See evolution timeline

Check Objectives

/objective               # View objective progress

Check Comms

/comms                   # View inter-Gee messages

Phase 14: Scaling Up

Multiple Gees

Create specialized Gees for different aspects of your workflow:

/mode create security-auditor
/mode create doc-writer
/mode create test-runner

Team Coordination

Put related Gees on a team:

Team: "code-quality"
├── security-auditor
├── test-runner
└── doc-writer

They can now see each other, share objectives, and communicate.

Endeavors

For large initiatives, create an endeavor that spans teams:

Endeavor: "v2-launch"
├── Team: "code-quality"
├── Team: "feature-dev"
└── Direct: "project-manager"

Autonomy Progression

The recommended path:

1. Start interactive (none) — use the Gee manually, shape its instructions
2. Go supervised (supervised) — let it suggest actions, you approve
3. Semi-autonomous (semi-autonomous) — reads freely, writes need approval
4. Full autonomous (autonomous) — runs within guardrails, no human in the loop

At each step, review the Gee’s identity evolution and tighten guardrails as needed.

Next Steps

• Gees & Teams — the identity system
• Identity & Subconscious — the three-layer cognitive architecture
• Modes — operational configurations
• Guardrails — safety constraints
• Missions & Objectives — purpose and work items