affaan-m/ECC · warning · SystemExit

Project hash not found in ~/.claude/homunculus/projects.json

Error message

Project hash not found in ~/.claude/homunculus/projects.json

What it means

This is not library code — it is a diagnostic Python heredoc inside TROUBLESHOOTING.md that scans ~/.claude/homunculus/projects.json for the entry whose 'root' equals os.getcwd(). If no entry matches, it raises SystemExit. It fires only when an operator runs the troubleshooting recipe from a directory that homunculus has not registered (exact-match on cwd).

Source

Thrown at TROUBLESHOOTING.md:69

- Project detection failures

**Solutions:**
```bash
# Check if observations are being recorded
ls ~/.claude/homunculus/projects/*/observations.jsonl

# Find the current project's hash id
python3 - <<'PY'
import json, os
registry_path = os.path.expanduser("~/.claude/homunculus/projects.json")
with open(registry_path) as f:
    registry = json.load(f)
for project_id, meta in registry.items():
    if meta.get("root") == os.getcwd():
        print(project_id)
        break
else:
    raise SystemExit("Project hash not found in ~/.claude/homunculus/projects.json")
PY

# View recent observations for that project
tail -20 ~/.claude/homunculus/projects/<project-hash>/observations.jsonl

# Back up a corrupted observations file before recreating it
mv ~/.claude/homunculus/projects/<project-hash>/observations.jsonl \
  ~/.claude/homunculus/projects/<project-hash>/observations.jsonl.bak.$(date +%Y%m%d-%H%M%S)

# Verify hooks are enabled
grep -r "observe" ~/.claude/settings.json
```

---

## Agent Harness Failures

### Agent Not Found

View on GitHub (pinned to 01e15490f0)

Solutions

1. Ensure homunculus hooks are enabled and the project has been observed (run a session in that root).
2. Run the heredoc from the exact registered project root (os.getcwd() must equal meta['root']).
3. Inspect ~/.claude/homunculus/projects.json and compare its 'root' values to your cwd.
4. Resolve symlinks before comparing, or relax the match to ancestor-of-cwd.

Example fix

// before
# run from a subdir -> 'Project hash not found in ~/.claude/homunculus/projects.json'

// after — resolve symlinks and fall back to ancestor match
import os, json
registry_path = os.path.expanduser("~/.claude/homunculus/projects.json")
cwd = os.path.realpath(os.getcwd())
with open(registry_path) as f:
    registry = json.load(f)
for project_id, meta in registry.items():
    if os.path.realpath(meta.get("root", "")) == cwd:
        print(project_id); break
else:
    for project_id, meta in registry.items():
        root = os.path.realpath(meta.get("root", ""))
        if cwd.startswith(root + os.sep):
            print(project_id); break
    else:
        raise SystemExit("Project hash not found in ~/.claude/homunculus/projects.json")

import os, json

def project_registered() -> bool:
    p = os.path.expanduser("~/.claude/homunculus/projects.json")
    if not os.path.isfile(p):
        return False
    cwd = os.path.realpath(os.getcwd())
    with open(p) as f:
        reg = json.load(f)
    return any(os.path.realpath(m.get("root", "")) == cwd for m in reg.values())

try:
    exec(open("troubleshoot.py").read())
except SystemExit as e:
    if "Project hash not found" in str(e):
        print("Run from the registered project root, or check ~/.claude/homunculus/projects.json")
    raise

When it happens

Trigger: Running the troubleshooting heredoc from a directory homunculus hasn't observed/registered; projects.json missing or empty; cwd is a subdirectory or symlink variant of the recorded root so exact string match fails.

Common situations: A new project never observed by homunculus hooks; cwd is a subdirectory of the registered root (exact match fails); projects.json deleted; running the recipe after cd-ing into a different checkout; a symlinked path that differs from the stored 'root'.

Related errors

• --config-dir must be an existing absolute directory.
• invalid qualification configuration
• --config-dir must exist and contain a regular sixtytwo.yaml
• invalid repo: expected non-empty string, got ${JSON.stringif
• Failed to load policy from ${resolvedPath}: ${error.message}

AI-assisted analysis of affaan-m/ECC@01e15490f0 (2026-08-13). Data as JSON: /api/errors/59c2f355dec0c398. Report an issue: GitHub.