Identity Resolution

Overview

Codeph needs to identify who is working on what to attribute events correctly and enable collaboration. It uses a priority-based resolution system for:

Project ID: Identifies the repository/project (e.g., owner/repo)
Actor ID: Identifies the contributor (e.g., GitHub username)
Repo ID: Local fallback identifier when project ID unavailable

Resolution Priority

From src/settings-store.ts and src/index.ts, Codaph resolves identity in this order:

Explicit CLI flag

Values passed directly via command-line flags

Environment variable

Values from environment variables

Saved settings

Values from ~/.codaph/settings.json or .codaph/project.json

Auto-detection

Git/GitHub detection fallback

Project ID Resolution

Resolution Logic

function resolveMubitProjectId(
  flags: Flags,
  cwd: string,
  settings?: CodaphSettings
): string | null {
  const loaded = loadSettingsOrDefault(settings);
  const projectSettings = getProjectSettings(loaded, cwd);
  
  // 1. Explicit flag or environment
  const explicit =
    getStringFlag(flags, 'mubit-project-id') ??
    process.env.CODAPH_PROJECT_ID ??
    process.env.MUBIT_PROJECT_ID ??
    projectSettings.mubitProjectId ??
    null;
  if (explicit && explicit.trim().length > 0) {
    return explicit.trim();
  }

  // 2. Auto-detect from git
  const detected = detectGitHubDefaults(cwd).projectId;
  return detected && detected.trim().length > 0 ? detected.trim() : null;
}

GitHub Auto-Detection

From src/settings-store.ts:50-119, Codaph extracts owner/repo from git remotes:

function detectGitHubDefaults(cwd: string): {
  projectId: string | null;
  actorId: string | null;
} {
  try {
    // Get remote URL from git
    const remoteUrl = execFileSync('git', ['remote', 'get-url', 'origin'], {
      cwd,
      encoding: 'utf8',
      stdio: ['ignore', 'pipe', 'ignore'],
    }).trim();

    // Parse owner/repo from GitHub URLs
    // https://github.com/owner/repo.git
    // [email protected]:owner/repo.git
    const match = remoteUrl.match(
      /github\.com[:\/]([^\/]+)\/([^\/]+?)(?:\.git)?$/
    );
    
    if (match) {
      const [, owner, repo] = match;
      return {
        projectId: `${owner}/${repo}`,
        actorId: detectGitHubActor()
      };
    }
  } catch {
    // Not a git repo or no origin remote
  }
  return { projectId: null, actorId: null };
}

Supported Git URL formats

https://github.com/owner/repo
https://github.com/owner/repo.git
[email protected]:owner/repo.git
ssh://[email protected]/owner/repo.git

Fallback: Repo ID

If project ID cannot be resolved, Codaph generates a local repo ID from the path:

function repoIdFromPath(pathname: string): string {
  const abs = resolve(pathname);
  return createHash('sha1').update(abs).digest('hex').slice(0, 12);
}

Example:

repoIdFromPath('/Users/alice/code/my-project')
// => '8f3d9e2a1c5b'

Repo IDs based on path hashes are unique per machine. For team collaboration, use explicit project IDs or GitHub remotes.

Actor ID Resolution

Resolution Logic

function resolveMubitActorId(
  flags: Flags,
  cwd: string,
  settings?: CodaphSettings
): string | null {
  const loaded = loadSettingsOrDefault(settings);
  
  // 1. Explicit flag or environment
  const explicit =
    getStringFlag(flags, 'mubit-actor-id') ??
    process.env.CODAPH_ACTOR_ID ??
    loaded.mubitActorId ??
    null;
  if (explicit && explicit.trim().length > 0) {
    return explicit.trim();
  }

  // 2. Auto-detect from GitHub
  const detected = detectGitHubDefaults(cwd).actorId;
  if (detected && detected.trim().length > 0) {
    return detected.trim();
  }

  // 3. Fallback to shell user
  const fallback = process.env.USER ?? process.env.USERNAME ?? null;
  return fallback && fallback.trim().length > 0 ? fallback.trim() : null;
}

GitHub Actor Detection

Codeph uses the GitHub CLI to detect your GitHub username:

function detectGitHubActor(): string | null {
  try {
    const login = execFileSync('gh', ['api', 'user', '--jq', '.login'], {
      encoding: 'utf8',
      stdio: ['ignore', 'pipe', 'ignore'],
    }).trim();
    return login.length > 0 ? login : null;
  } catch {
    // gh CLI not available or not authenticated
    return null;
  }
}

Install and authenticate the GitHub CLI (gh auth login) for automatic actor detection.

Git Config Fallback

If GitHub CLI is unavailable, Codaph falls back to git config:

git config user.email
# => [email protected]

Or shell environment variables:

echo $USER
# => alice

Configuration Examples

Explicit Configuration

Set identities explicitly via CLI:

codaph setup \
  --mubit-actor-id alice \
  --mubit-project-id owner/repo

Or via project init:

codaph init \
  --name "My Project" \
  --mubit-project-id owner/repo

Environment Variables

Set via environment for CI/scripted usage:

export CODAPH_ACTOR_ID=ci-bot
export CODAPH_PROJECT_ID=owner/repo
export MUBIT_API_KEY=sk-...

codaph init --yes
codaph push

Auto-Detection Setup

Let Codaph auto-detect from git:

Ensure git remote

git remote -v
# origin  https://github.com/owner/repo (fetch)
# origin  https://github.com/owner/repo (push)

Authenticate GitHub CLI

gh auth login
gh auth status
# ✓ Logged in to github.com as alice

Initialize Codaph

codaph init
# Codaph will auto-detect:
# - Project ID: owner/repo (from git remote)
# - Actor ID: alice (from gh CLI)

Settings Storage

Codeph stores resolved settings in two locations:

Global Settings

Location: ~/.codaph/settings.json

{
  "schema": "codaph.settings.v2",
  "mubitApiKey": "sk-...",
  "mubitActorId": "alice",
  "openAiApiKey": "sk-...",
  "projects": {
    "/Users/alice/code/my-project": {
      "projectName": "My Project",
      "mubitProjectId": "owner/repo",
      "mubitRunScope": "project",
      "agentProviders": ["codex", "claude-code"]
    }
  }
}

Project Settings

Location: .codaph/project.json

{
  "schema": "codaph.project.v2",
  "projectPath": "/Users/alice/code/my-project",
  "repoId": "owner/repo",
  "projectLabel": "My Project",
  "mubitProjectId": "owner/repo",
  "mubitRunScope": "project",
  "agentProviders": ["codex", "claude-code"],
  "syncAutomation": {
    "enabled": true,
    "gitPostCommit": true,
    "agentComplete": true
  },
  "createdAt": "2024-03-01T10:00:00Z",
  "updatedAt": "2024-03-01T10:00:00Z"
}

Identity in Event Envelopes

Resolved identities appear in every captured event:

interface CapturedEventEnvelope {
  eventId: string;
  source: AgentSource;
  repoId: string;        // Project ID or path-based repo ID
  actorId: string | null; // Resolved actor ID
  sessionId: string;
  threadId: string | null;
  ts: string;
  eventType: string;
  payload: Record<string, unknown>;
  reasoningAvailability: ReasoningAvailability;
}

Troubleshooting

Actor ID shows as 'unknown' or null

Cause: GitHub CLI not authenticated or git config not setSolution:

# Option 1: Authenticate GitHub CLI
gh auth login

# Option 2: Set git config
git config --global user.email "[email protected]"

# Option 3: Set explicitly
codaph setup --mubit-actor-id alice

Project ID is a hash instead of owner/repo

Cause: No GitHub remote detectedSolution:

# Check current remote
git remote -v

# Add GitHub remote
git remote add origin https://github.com/owner/repo

# Or set explicitly
codaph init --mubit-project-id owner/repo

Different actors see different timelines

Cause: Using session-scoped run IDs instead of project scopeSolution:

# Check current run scope
codaph status --json | jq '.mubitRunScope'

# Switch to project scope
codaph init --mubit-run-scope project --force

Team members have different project IDs

Cause: Inconsistent configuration or different git remotesSolution:

# Everyone should use the same project ID
# Option 1: Ensure consistent git remotes
git remote set-url origin https://github.com/owner/repo

# Option 2: Set explicitly in environment
echo "export CODAPH_PROJECT_ID=owner/repo" >> ~/.bashrc

# Option 3: Document project ID in team README
codaph init --mubit-project-id owner/repo

Best Practices

Use GitHub remotes

Configure GitHub origin remotes for automatic project ID detection:

git remote add origin https://github.com/owner/repo

Authenticate GitHub CLI

Run gh auth login for automatic actor ID detection

Explicit IDs for teams

Document explicit project IDs in team documentation:

# In team README or setup script
codaph init --mubit-project-id owner/repo

Verify before first sync

Check resolved identities with codaph doctor:

codaph doctor --mubit
# Shows: project ID, actor ID, repo ID, run scope

Architecture

How identity flows through the system

Collaboration

Team collaboration with shared identity

Setup Command

Configure global settings

Init Command

Initialize project settings

Get Started

Core Concepts

Guides

Advanced

Help

Identity Resolution

Overview

Resolution Priority

Project ID Resolution

Resolution Logic

GitHub Auto-Detection

Fallback: Repo ID

Actor ID Resolution

Resolution Logic

GitHub Actor Detection

Git Config Fallback

Configuration Examples

Explicit Configuration

Environment Variables

Auto-Detection Setup

Settings Storage

Global Settings

Project Settings

Identity in Event Envelopes

Troubleshooting

Best Practices

See Also

Architecture

Collaboration

Setup Command

Init Command

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Advanced

Help

​Overview

​Resolution Priority

​Project ID Resolution

​Resolution Logic

​GitHub Auto-Detection

​Fallback: Repo ID

​Actor ID Resolution

​Resolution Logic

​GitHub Actor Detection

​Git Config Fallback

​Configuration Examples

​Explicit Configuration

​Environment Variables

​Auto-Detection Setup

​Settings Storage

​Global Settings

​Project Settings

​Identity in Event Envelopes

​Troubleshooting

​Best Practices

​See Also

Architecture

Collaboration

Setup Command

Init Command

Build docs developers (and LLMs) love

Overview

Resolution Priority

Project ID Resolution

Resolution Logic

GitHub Auto-Detection

Fallback: Repo ID

Actor ID Resolution

Resolution Logic

GitHub Actor Detection

Git Config Fallback

Configuration Examples

Explicit Configuration

Environment Variables

Auto-Detection Setup

Settings Storage

Global Settings

Project Settings

Identity in Event Envelopes

Troubleshooting

Best Practices

See Also