Gees & Teams

A Gee is a persistent AI identity — not a chat session, but a named agent with its own memory, mission, guardrails, tools, and evolving sense of self. When you run gee-code, you’re operating through a Gee. Every tool call, every objective, every credential resolves through that Gee’s scope.

Anatomy of a Gee

A Gee is defined by its configuration stored at ~/.gee-code/modes/{name}/. Here’s what it carries:

Identity

Field	Description
name	Unique identifier (lowercase, hyphens)
display_name	Human-readable name
description	What this Gee does
role	Job title — “Security Auditor”, “UI Designer”, etc.
gee_id	Email-like identity (e.g., analyst@gee.pub)

The role and description feed into the system prompt, shaping how the AI behaves. A Gee with role “Security Auditor” reasons differently than one titled “UI Designer”.

What a Gee Owns

~/.gee-code/modes/{name}/
├── mode.json               # Core configuration
├── settings.json           # Runtime preferences (model, skills, rlm)
├── instructions.md         # System instructions (the Gee's playbook)
├── rules.md                # Hard rules injected into every prompt
├── mission.md              # Guiding mission (tamper-protected)
├── identity.md             # Evolving sense-of-self document
├── identity_history/       # Archived identity snapshots
├── guardrails.json         # Safety constraints
├── heartbeat.md            # Checklist for autonomous activations
├── agents/                 # Mode-specific agent definitions
├── skills/                 # Mode-specific skills
├── flights/                # Flight templates
├── swarms/                 # Swarm configurations
├── comms/                  # Inter-Gee messaging
│   ├── inbox.jsonl
│   ├── outbox.jsonl
│   └── bulletin.jsonl
└── output/                 # Autonomous result delivery

Memory Visibility

Each Gee has a memory_visibility setting:

Level	Sees
self	Only its own memories (default)
system	Its own + system-level memories
omniscient	All memories across all Gees

Component Filters

A Gee doesn’t have to see everything. Filters control which agents, skills, MCP servers, and other components are available:

{
  "agents": { "available": ["coder", "reviewer"], "disabled": ["admin"] },
  "skills": { "bundled": ["commit"], "disabled": ["deploy"] },
  "mcp": { "enabled": ["filesystem"] }
}

Managing Gees

/gee                    # Open interactive browser (Gees | Teams | Endeavors | Objectives)
/mode create analyst    # Create a new Gee
/mode switch analyst    # Switch to it
/mode delete analyst    # Delete it

The Gee browser provides a full management interface where you can create, edit, configure, and monitor Gees.

Teams

Teams group Gees together for collaboration and shared resources:

{
  "name": "content-team",
  "description": "Content creation and review",
  "repos": ["https://github.com/user/docs-site"]
}

What Teams Provide

• Shared repos — team repos merge into each member’s effective workspace
• Visibility — Gees in the same team can see each other (sibling awareness)
• Shared guardrails — team-level guardrails apply to all members
• Shared objectives — objectives assigned to a team reach all members

A Gee can belong to multiple teams. Solo Gees (no teams) see no siblings.

Endeavors

Endeavors are project-scoped groupings that sit above teams — representing a coordinated effort across multiple teams and individual Gees. Think of them as initiatives or projects: a product launch, a migration, a research spike. They exist to coordinate work that cuts across team boundaries.

Creating an Endeavor

Use the Gee browser to create endeavors:

/gee

Navigate to the Endeavors tab. You can also create endeavors implicitly — assigning a Gee to a non-existent endeavor auto-creates it.

Endeavor Configuration

Endeavors are stored at ~/.gee-code/endeavors/{name}/:

~/.gee-code/endeavors/q1-launch/
├── config.json         # Name, description, teams, direct gees
└── guardrails.json     # Endeavor-level guardrails (optional)

The config defines membership:

{
  "name": "q1-launch",
  "description": "Ship v2.0 by end of Q1",
  "teams": ["frontend-team", "backend-team"],
  "gees": ["project-manager"]
}

Membership

Endeavors have two types of members:

Type	How they join	Resolution
Direct Gees	Listed in gees array	The Gee is a direct member
Teams	Listed in teams array	All Gees in the team become members

A Gee’s effective endeavor membership is computed from both paths — direct membership plus any endeavors that include its teams. This means a Gee can be part of an endeavor without being explicitly listed, simply by being on a member team.

Objective Assignment

Objectives can be assigned to endeavors, which means every Gee in that endeavor sees the objective. The resolution chain checks:

1. Is the objective assigned to all Gees? (assign_all)
2. Is this Gee directly assigned?
3. Is this Gee in an assigned endeavor?
4. Is this Gee on an assigned team?

This lets you broadcast work to an entire initiative with a single assignment.

Endeavor Guardrails

Endeavors can define their own guardrails in guardrails.json. These are additive — they merge with team and Gee-level guardrails, never loosening constraints:

Effective guardrails = Gee guardrails + Team guardrails + Endeavor guardrails

Managing Endeavors in The Terminal

The Terminal’s Endeavors Panel provides a full management interface for Gees, teams, and endeavors. It includes three views:

View	Tab Label	What It Shows
Agents	Gees	Mode selector, autonomy settings, assignments, mission, objectives, file editor, guardrails
Comms	Teams	Inter-Gee inbox and outbox messages
Thinking	Swarms	Live daemon event stream (tool calls, activations, reasoning)

From the Agents view you can:

• Configure autonomy level, heartbeat, cost limits, and model clamping
• Assign teams and endeavors (with auto-creation for new names)
• Edit mission statements and mode files (identity, heartbeat, instructions, rules)
• Create and manage objectives with status, priority, and multi-level assignment
• Set guardrails and fine-grained permission filters

Lifecycle

Deleting an endeavor does not cascade to its teams or Gees — they continue to exist independently. The endeavor is just an organizational container; removing it simply dissolves the grouping.

The Entity Hierarchy

Endeavor ("q1-launch")
├── Teams
│   ├── "frontend-team" -> [gee-a, gee-b]
│   └── "backend-team"  -> [gee-c, gee-d]
├── Direct Gees
│   └── "project-manager"
├── Guardrails (additive)
└── Objectives (visible to all members)

Scoped Resolution

Many systems resolve values through the hierarchy:

System	Resolution Rule
Credentials	Most specific wins — Gee overrides team overrides global
Guardrails	Additive — rules merge, limits take the most restrictive value
Objectives	Union — a Gee sees objectives from all its scopes
Repos	Merge — effective repos = own + team repos
Permissions	Intersection — tightest allowed set wins

The key principle: adding constraints at a higher scope only tightens, never loosens.

Inter-Gee Communication

Gees communicate through the Comms system:

Type	Purpose
message	Direct one-way communication
request	Collaboration ask (pending -> accepted -> completed)
broadcast	Announcement to team members
bulletin	Public board post visible to everyone

/comms                  # View messages
/comms send reviewer "Build fixed, CI green"

Unread messages and pending requests are automatically surfaced in the system prompt on every activation.

Identity Evolution

Every Gee has an evolving identity document with sections for who it is, what it knows, its track record, priorities, and problem-solving approach. After each autonomous activation, the identity evolves based on what happened — updating stats, knowledge, and learnings.

/identity               # View current identity
/identity history       # See evolution timeline

The Mission and Boundaries sections are protected from modification by the AI.

Gees and Modes

In Gee-Code, a “Gee” and a “Mode” are the same entity at the config level. The distinction is conceptual:

• Gee emphasizes the persistent identity (name, role, memory, mission)
• Mode emphasizes the operational profile (model, agents, autonomy settings)

When you create a mode, you’re creating a Gee. The terms are interchangeable.

Next Steps

• Modes — operational configurations
• Missions & Objectives — work items and purpose
• Guardrails — safety constraints
• Operating Gees — the full lifecycle guide