{"record":{"id":"59c2f355dec0c398","repo":"affaan-m/ECC","slug":"project-hash-not-found-in-claude-homunculus-pro","errorCode":null,"errorMessage":"Project hash not found in ~/.claude/homunculus/projects.json","messagePattern":"Project hash not found in ~/\\.claude/homunculus/projects\\.json","errorType":"exception","errorClass":"SystemExit","httpStatus":null,"severity":"warning","filePath":"TROUBLESHOOTING.md","lineNumber":69,"sourceCode":"- Project detection failures\n\n**Solutions:**\n```bash\n# Check if observations are being recorded\nls ~/.claude/homunculus/projects/*/observations.jsonl\n\n# Find the current project's hash id\npython3 - <<'PY'\nimport json, os\nregistry_path = os.path.expanduser(\"~/.claude/homunculus/projects.json\")\nwith open(registry_path) as f:\n    registry = json.load(f)\nfor project_id, meta in registry.items():\n    if meta.get(\"root\") == os.getcwd():\n        print(project_id)\n        break\nelse:\n    raise SystemExit(\"Project hash not found in ~/.claude/homunculus/projects.json\")\nPY\n\n# View recent observations for that project\ntail -20 ~/.claude/homunculus/projects/<project-hash>/observations.jsonl\n\n# Back up a corrupted observations file before recreating it\nmv ~/.claude/homunculus/projects/<project-hash>/observations.jsonl \\\n  ~/.claude/homunculus/projects/<project-hash>/observations.jsonl.bak.$(date +%Y%m%d-%H%M%S)\n\n# Verify hooks are enabled\ngrep -r \"observe\" ~/.claude/settings.json\n```\n\n---\n\n## Agent Harness Failures\n\n### Agent Not Found","sourceCodeStart":51,"sourceCodeEnd":87,"githubUrl":"https://github.com/affaan-m/ECC/blob/01e15490f04e29cfefe3896951f43db46994d8ee/TROUBLESHOOTING.md#L51-L87","documentation":"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).","triggerScenarios":"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.","commonSituations":"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'.","solutions":["Ensure homunculus hooks are enabled and the project has been observed (run a session in that root).","Run the heredoc from the exact registered project root (os.getcwd() must equal meta['root']).","Inspect ~/.claude/homunculus/projects.json and compare its 'root' values to your cwd.","Resolve symlinks before comparing, or relax the match to ancestor-of-cwd."],"exampleFix":"// before\n# run from a subdir -> 'Project hash not found in ~/.claude/homunculus/projects.json'\n\n// after — resolve symlinks and fall back to ancestor match\nimport os, json\nregistry_path = os.path.expanduser(\"~/.claude/homunculus/projects.json\")\ncwd = os.path.realpath(os.getcwd())\nwith open(registry_path) as f:\n    registry = json.load(f)\nfor project_id, meta in registry.items():\n    if os.path.realpath(meta.get(\"root\", \"\")) == cwd:\n        print(project_id); break\nelse:\n    for project_id, meta in registry.items():\n        root = os.path.realpath(meta.get(\"root\", \"\"))\n        if cwd.startswith(root + os.sep):\n            print(project_id); break\n    else:\n        raise SystemExit(\"Project hash not found in ~/.claude/homunculus/projects.json\")","handlingStrategy":"validation","validationCode":"import os, json\n\ndef project_registered() -> bool:\n    p = os.path.expanduser(\"~/.claude/homunculus/projects.json\")\n    if not os.path.isfile(p):\n        return False\n    cwd = os.path.realpath(os.getcwd())\n    with open(p) as f:\n        reg = json.load(f)\n    return any(os.path.realpath(m.get(\"root\", \"\")) == cwd for m in reg.values())","typeGuard":null,"tryCatchPattern":"try:\n    exec(open(\"troubleshoot.py\").read())\nexcept SystemExit as e:\n    if \"Project hash not found\" in str(e):\n        print(\"Run from the registered project root, or check ~/.claude/homunculus/projects.json\")\n    raise","preventionTips":["Run homunculus troubleshooting recipes from the exact registered project root.","Confirm hooks are enabled so projects get observed and registered.","Back up projects.json before editing.","Resolve symlinks before comparing paths."],"tags":["homunculus","troubleshooting","config","registry"],"backgroundTag":null,"analyzedSha":"01e15490f04e29cfefe3896951f43db46994d8ee","analyzedAt":"2026-08-13T00:31:08.655Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}