{"id":50520332,"url":"https://github.com/kinkos1234/comad-world","last_synced_at":"2026-06-03T03:31:18.455Z","repository":{"id":349270616,"uuid":"1201704359","full_name":"kinkos1234/comad-world","owner":"kinkos1234","description":"Config-driven AI agent system for any domain. 6 modules, 1 YAML file. Swap a preset, get a new knowledge system.","archived":false,"fork":false,"pushed_at":"2026-05-30T02:06:17.000Z","size":13913,"stargazers_count":18,"open_issues_count":0,"forks_count":11,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-30T03:20:44.225Z","etag":null,"topics":["ai-agents","bun","claude-code","config-driven","graphrag","knowledge-graph","mcp","neo4j","python","typescript"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kinkos1234.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-05T03:25:21.000Z","updated_at":"2026-05-30T02:06:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kinkos1234/comad-world","commit_stats":null,"previous_names":["kinkos1234/comad-world"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/kinkos1234/comad-world","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kinkos1234%2Fcomad-world","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kinkos1234%2Fcomad-world/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kinkos1234%2Fcomad-world/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kinkos1234%2Fcomad-world/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kinkos1234","download_url":"https://codeload.github.com/kinkos1234/comad-world/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kinkos1234%2Fcomad-world/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33847264,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","bun","claude-code","config-driven","graphrag","knowledge-graph","mcp","neo4j","python","typescript"],"created_at":"2026-06-03T03:31:17.630Z","updated_at":"2026-06-03T03:31:18.447Z","avatar_url":"https://github.com/kinkos1234.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eComad World\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eYou read arXiv every morning. By Friday, you can't remember what Tuesday's paper argued.\u003cbr\u003e\n  Comad World turns each paper you read into a graph edge, a sharpened retrieval lens, a calibrated prediction.\u003cbr\u003e\n  Your reading stops evaporating — it compounds into a system that thinks alongside you.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-blue.svg\" alt=\"License: MIT\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Claude%20Code-compatible-blueviolet\" alt=\"Claude Code\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/config--driven-yes-22D3EE\" alt=\"Config Driven\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  6 AI agents that \u003cb\u003ecrawl → understand → simulate → curate → remember → evolve\u003c/b\u003e\u003cbr\u003e\n  Two feedback loops: the system improves itself, and improves your coding.\u003cbr\u003e\n  Change one YAML file, get a whole new knowledge system.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#quickstart\"\u003eQuickstart\u003c/a\u003e · \u003ca href=\"#architecture\"\u003eArchitecture\u003c/a\u003e · \u003ca href=\"#modules\"\u003eModules\u003c/a\u003e · \u003ca href=\"#customization\"\u003eCustomization\u003c/a\u003e · \u003ca href=\"#presets\"\u003ePresets\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/demo.gif\" alt=\"Comad World Demo · v0.3.0\" width=\"720\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003e🎬 \u003ca href=\"docs/promo-v0.3.0.mp4\"\u003eFull-quality 1920×1080 MP4\u003c/a\u003e · \u003ca href=\"docs/promo-v0.3.0-60fps.mp4\"\u003e60fps\u003c/a\u003e · 30s · 27-angle expert review · Gap Packs A~D\u003c/sub\u003e\n\u003c/p\u003e\n\n---\n\n## What You Get\n\n| | Without Comad World | With Comad World |\n|---|---|---|\n| **Collecting** | Manually check 20+ sites, forget half | `ear` auto-detects and archives from RSS, HN, arXiv, GitHub |\n| **Organizing** | Bookmarks pile up, no connections | `brain` builds a knowledge graph — 10,000+ nodes, searchable via GraphRAG |\n| **Analyzing** | Read each article, form opinions alone | `eye` runs simulations through 5 core strategic lenses (tiered system), tracks prediction accuracy |\n| **Remembering** | Context lost between sessions | `sleep` consolidates memory, `voice` automates recurring workflows |\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eKey numbers from a real deployment\u003c/b\u003e\u003c/summary\u003e\n\n- **60,000+** graph nodes, **150,000+** relationships from ongoing crawling\n- **31** RSS feeds monitored (OpenAI, Anthropic, Google, Meta, arXiv, researcher blogs)\n- **30+ MCP tools** across 4 servers (brain 21, eye 7, sleep 2, photoshop) — all auto-connected\n- **Entity-level confidence scoring** (0.0–1.0) for trust boundary tracking\n- **Content guard** — injection detection on all crawled content (10 threat patterns)\n- **Built-in performance monitoring** via `comad_brain_perf` MCP tool\n- **$0/day** additional cost with Claude Max subscription (all LLM calls via CLI, local Ollama for eye)\n- **1,422** tests across all modules (brain + eye suites)\n\n\u003c/details\u003e\n\n---\n\n## 🌍 What is Comad World?\n\nComad World is a modular AI agent system built on [Claude Code](https://docs.anthropic.com/en/docs/claude-code). It connects six specialized agents into a pipeline that collects information, builds a knowledge graph, runs simulations, curates content, manages memory, and automates workflows — plus an always-on **loopy-era** self-evolution harness (the 9th module) that keeps the system measuring and learning — all driven by a single configuration file.\n\n```\near (listen) → brain (think) → eye (predict)\n                  ↑\nphoto (edit)    sleep (remember)    voice (automate)\n```\n\n**The key idea:** every domain-specific setting lives in `comad.config.yaml`. Swap the config, and the entire system adapts — from what RSS feeds to crawl, to what arXiv categories to watch, to how articles are classified.\n\n---\n\n## Who is this for?\n\n- **Knowledge workers** who want a persistent, queryable memory of what they've read.\n- **Developers** building on Claude Code who want an MCP-powered knowledge graph.\n- **Domain experts** (AI/ML, finance, biotech, web dev) who need a focused research assistant — swap a YAML preset, the whole stack adapts.\n\n## Quickstart\n\nPrerequisites: [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Docker](https://docker.com/), [Bun](https://bun.sh/), [Python 3.13+](https://python.org/).\n\n```bash\ngit clone https://github.com/kinkos1234/comad-world.git \u0026\u0026 cd comad-world\ncp presets/ai-ml.yaml comad.config.yaml   # or web-dev / finance / biotech\n./install.sh                               # deps + Neo4j schema\ncd brain \u0026\u0026 bun run setup \u0026\u0026 bun run mcp   # start MCP server\nzsh brain/scripts/schedule-install.sh      # OS-aware scheduler (below)\n```\n\n### Scheduled jobs (cross-platform)\n\n| OS | Scheduler | Why |\n|---|---|---|\n| macOS | LaunchAgents (`gui/\u003cuid\u003e`) | cron runs outside Aqua → keychain-locked; LaunchAgents inherit the GUI session. |\n| Linux / WSL | cron | Session keychain propagates. |\n| Windows | Task Scheduler (`LogonType=Interactive`) | DPAPI/OAuth stays unlocked while logged on. Uses bun directly — no shell. |\n\nAll three reuse the existing Claude Max OAuth — no extra API key. Per-platform install details: `brain/scripts/launchd/README.md`.\n\nFull catalog of the 11 scheduled jobs (dependencies, cron expressions, missing-run recovery) lives in [`docs/cron-catalog.md`](docs/cron-catalog.md). A boot-time catch-up agent (`com.comad.cron-catchup`) replays any LaunchAgent that would have fired while the laptop was asleep, so the Monday analysis pipeline still runs even if you opened the lid mid-day.\n\n### Upgrading\n\nAlready have Comad World installed? After `./install.sh` you get a `comad` command on your PATH (symlink into `~/.local/bin/`) plus a root `Makefile` with matching shortcuts:\n\n```bash\ncomad status          # show VERSION + module SHAs (any module dirty?)\ncomad upgrade         # full upgrade — main repo + 6 modules + deps + agents\ncomad upgrade --dry-run   # preview what would change (no writes)\ncomad backups         # list snapshots created by previous upgrades\ncomad rollback \u003cts\u003e   # restore an earlier snapshot\ncomad lock            # regenerate comad.lock from current SHAs\ncomad help\n\n# Makefile equivalents\nmake status\nmake upgrade\nmake upgrade-check          # = comad upgrade --dry-run\nmake backups\nmake rollback TS=\u003cts\u003e\nmake test                   # full suite (brain + eye)\nmake clean                  # dry-run: preview runtime artifacts to remove\nmake clean-apply            # actually remove caches, logs, build artifacts\nmake clean-deep             # also nuke node_modules / .venv (slow, ~3.6 GB)\nmake render                 # regenerate path-aware templates\nmake validate-config        # check comad.config.yaml + presets against the schema\n```\n\nConfiguration rules are documented in [ADR 0002 — `comad.config.yaml` Contract](docs/adr/0002-config-contract.md). The canonical JSON Schema lives at `schema/comad.config.schema.json` and is validated by the `config-schema-validation` CI job on every push.\n\nRepository strategy is documented in [ADR 0001 — Repository Strategy](docs/adr/0001-repository-strategy.md). The short version: the umbrella owns the wiring (installer, scripts, `Makefile`, `VERSION`, `comad.lock`, `docs/`), each module directory is owned by its own nested `.git`, and `comad.lock` pins the combination. A `Structure Guard` CI job rejects PRs that duplicate module files at the root or track build artifacts.\n\nIf you installed Comad World before the `comad` command existed, bootstrap it once:\n\n```bash\ncd /path/to/comad-world\ngit pull origin main                                      # pull upgrade.sh + scripts/comad\nln -s \"$(pwd)/scripts/comad\" \"$HOME/.local/bin/comad\"     # or re-run ./install.sh\nexport PATH=\"$HOME/.local/bin:$PATH\"                      # if not already on PATH\ncomad upgrade --dry-run\n```\n\nThe underlying script (`scripts/upgrade.sh`) is always available too:\n\n```bash\n./scripts/upgrade.sh --dry-run\n./scripts/upgrade.sh --rollback \u003cts\u003e\n```\n\nWhat it does:\n\n1. **Pre-flight** — refuses to run on a dirty working tree (use `--force` to override); warns about running Comad services (ports 3000/8000/7687/7688); diffs new `.env.example` keys against your `.env`.\n2. **Snapshot** — copies `comad.config.yaml`, `comad.lock`, `VERSION`, `.env`, and `~/.claude/agents/` into `.comad/backups/\u003ctimestamp\u003e/`.\n3. **Pull** — fast-forwards the main repo and each of the six module repos (brain / ear / eye / photo / sleep / voice) on their tracked branch, recording per-module result + elapsed time.\n4. **Dependencies** — reruns `bun install` (brain), `pip install -r eye/requirements.txt`, and `npm ci` (eye/frontend) as applicable.\n5. **Agents \u0026 configs** — redeploys `comad-sleep` and `comad-photo` agents, replaces the `COMAD-VOICE` section of `~/.claude/CLAUDE.md` in place, and reruns `scripts/apply-config.sh` to regenerate module configs from `comad.config.yaml`.\n6. **Summary** — per-module success/failure table, CHANGELOG excerpt since the previous `VERSION`, and updated `comad.lock`.\n\nThe version contract is `VERSION` (root) + `comad.lock` (pins every module SHA). GitHub Actions runs `scripts/upgrade.sh --dry-run --force` on every PR that touches the upgrader, so the happy path stays green.\n\nIf you want to pin your install to a known-good combination, commit `comad.lock` and treat it like `package-lock.json`.\n\n### Where can I clone the repo?\n\nAnywhere. The repo is path-agnostic — pick any folder, any name:\n\n```bash\ngit clone https://github.com/kinkos1234/comad-world.git ~/Desktop/my-agents\ncd ~/Desktop/my-agents \u0026\u0026 ./install.sh\ncomad status   # shows the new path\n```\n\n`scripts/comad` follows its own symlink (`~/.local/bin/comad`) to derive the repo root. `scripts/upgrade.sh` uses `BASH_SOURCE`, `brain/scripts/launchd/install.sh` uses `${0:A:h}`, and `scripts/render-templates.sh` rewrites `{{COMAD_ROOT}}` placeholders in `*.example` files (currently `sleep/.mcp.json.example`) into per-machine absolute paths at install/upgrade time. There are no `/Users/\u003cauthor\u003e` hardcodes left.\n\n---\n\n## Demo: Swap a Preset, Change Everything\n\n```bash\n# Start with AI/ML preset\n$ head -5 comad.config.yaml\nprofile:\n  name: \"Comad AI Lab\"\n  language: \"en\"\n  description: \"AI/ML knowledge system\"\n\n# Crawl AI sources (31 RSS feeds, 10 arXiv categories)\n$ cd brain \u0026\u0026 bun run crawl:hn\n[hn-crawler] Keywords: 48, RSS feeds: 22, HN queries: 8\n[hn-crawler] HN stories: 347\n[hn-crawler] RSS results: 412\n[hn-crawler] Wrote 583 articles to data/articles-crawl.json\n\n# Now switch to Finance\n$ cp presets/finance.yaml comad.config.yaml\n$ ./scripts/apply-config.sh\n  ✓ ear/interests.md\n  ✓ ear/CLAUDE.md\n\n# Same crawl command, completely different sources\n$ bun run crawl:hn\n[hn-crawler] Keywords: 31, RSS feeds: 10, HN queries: 7\n[hn-crawler] HN stories: 89\n[hn-crawler] RSS results: 156\n[hn-crawler] Wrote 201 articles to data/articles-crawl.json\n\n# ear/interests.md automatically updated:\n$ head -6 ear/interests.md\n# User Interest Profile\n## High Priority (Core Focus)\n- Quantitative Finance (QuantConnect, Zipline, Backtrader)\n- Market Data / Analysis\n- DeFi / Crypto\n- Risk Management\n```\n\nOne YAML change. Different feeds, different keywords, different categories, different relevance criteria.\n\n---\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────┐\n│                  comad.config.yaml                   │\n│  (interests, sources, keywords, categories, stack)   │\n└───────────┬───────────┬───────────┬─────────────────┘\n            │           │           │\n    ┌───────▼──┐  ┌─────▼────┐  ┌──▼──────┐\n    │   ear    │  │  brain   │  │  eye    │\n    │ (curate) │→ │ (graph)  │→ │(predict)│\n    └──────────┘  └──────────┘  └─────────┘\n                       │\n    ┌──────────┐  ┌────▼─────┐  ┌─────────┐\n    │  photo   │  │  sleep   │  │  voice  │\n    │  (edit)  │  │(remember)│  │(automate│\n    └──────────┘  └──────────┘  └─────────┘\n```\n\n### Data Flow\n\nAll modules are accessible via natural language — no slash commands needed. 4 MCP servers auto-connect on session start.\n\n1. **Ear** detects articles in Discord, classifies relevance using your interests, archives to markdown\n2. **Brain** crawls RSS/arXiv/GitHub filtered by your keywords, builds a Neo4j knowledge graph with entities and relationships. Content guard scans all crawled data. JS-heavy pages automatically rendered via **Browse**\n3. **Eye** takes any text, converts to ontology, runs multi-round simulations, generates analysis through 5 core strategic lenses with prediction tracking (7 MCP tools)\n4. **Photo** corrects images via Photoshop MCP — auto-launches Photoshop when needed (domain-agnostic)\n5. **Sleep** consolidates Claude Code memory across all projects (domain-agnostic)\n6. **Voice** provides workflow automation triggers for Claude Code (domain-agnostic)\n7. **Search** discovers repos across GitHub/npm/PyPI/arXiv, evaluates them, generates adoption plans, tests in sandbox — the system improves itself\n\n### What's Config-Driven vs. Domain-Agnostic\n\n| Module | Config-Driven | Domain-Agnostic |\n|--------|:---:|:---:|\n| **ear** | interests, categories, must-read stack, relevance thresholds | archive format, Discord integration, digest generation |\n| **brain** | RSS feeds, HN queries, arXiv categories, GitHub topics, entity extraction prompts | Neo4j schema, GraphRAG, MCP tools, MetaEdge engine |\n| **eye** | — | entire engine: ontology, simulation, 5 tiered lenses, prediction tracking |\n| **photo** | — | everything (works with any photo) |\n| **sleep** | — | everything (manages any Claude Code memory) |\n| **voice** | — | everything (workflow triggers are generic) |\n\n---\n\n## Modules\n\n### Brain — Knowledge Graph \u0026 GraphRAG\n\nNeo4j-based knowledge graph that crawls, extracts entities, and answers questions via MCP.\n\n- **20+ MCP tools** for querying, searching, and analyzing the graph\n- **Dual-retriever GraphRAG** — Local + Global + Temporal 3-way search. Benchmark (50 questions): **93% entity recall, 93% grounding rate, 13.8s p50 latency**\n- **Graph-driven query expansion** — concept keywords (hallucination, agent, GPU, …) expanded via Neo4j co-occurrence + static fallback; 1h LRU cache\n- **Grounded synthesis** — every cited entity is verified to exist in the graph (hallucination-resistant answer metric)\n- **MetaEdge engine** — 10 rules for automated relationship inference\n- **Entity \u0026 claim confidence** — every node scored 0.0–1.0 (explicit mention=0.9+, inferred=0.6–0.8, uncertain=0.3–0.5)\n- **Claim tracking** — fact/opinion/prediction with confidence scores, decay, and timelines\n- **Performance monitoring** — latency tracking for all MCP tools, GraphRAG pipeline, and crawlers\n- **Community detection** — hierarchical clustering for topic discovery\n- **Content guard** — prompt injection detection on all crawled content (10 threat patterns + invisible Unicode scanning)\n- **Config-driven crawlers** — RSS, arXiv, GitHub crawlers load sources from `comad.config.yaml`\n\n```bash\ncd brain\nbun install \u0026\u0026 bun run setup\nbun run mcp  # Start MCP server\n```\n\n### Ear — Content Curator\n\nDiscord bot that detects articles, classifies relevance, and archives with structured metadata.\n\n- **3-tier relevance**: Must-Read (~15%) → Recommended (~65%) → Reference (~20%)\n- **Configurable categories** from `comad.config.yaml`\n- **Daily digest** auto-generation in HTML — nightly cron writes `ear/digests/YYYY-MM-DD-digest.html`\n- **Auto-ingest to /search** — must-read articles in core categories (AI/LLM, Tool, OpenSource, …) are fed into the search pipeline daily, closing the loop ear → brain → /search → adoption\n- **YAML frontmatter** for every archived article\n- **Two operation modes** — Mode A (interactive `ccd`, real-time, terminal-bound) or Mode B (`ear-poll` LaunchAgent, 15-min REST polling, 24/7, zero IDENTIFY quota). See [guide](https://kinkos1234.github.io/comad/guide/ear.html).\n\n### Eye — Prediction Simulation Engine\n\nOntology-based simulation that converts text to knowledge graph and runs multi-round impact analysis.\n\n- **6 analytical spaces**: hierarchy, temporal, recursive, structural, causal, cross-space\n- **Tiered lens system**: 5 core (Sun Tzu, Adam Smith, Taleb, Kahneman, Meadows) + 2 optional (Clausewitz, Darwin) + 3 legacy\n- **Prediction tracking**: closed-loop learning — records predictions with verification deadlines, measures accuracy over time\n- **Full pipeline**: ingestion → graph → community → simulation → analysis → report\n- **7 MCP tools**: analyze, preflight, Q\u0026A, jobs, report, lenses, status — all callable via natural language\n- **Web UI**: FastAPI backend + Next.js frontend\n- **AI-readable pages**: server-side rendered report/analysis content, per-page OG + JSON-LD metadata, explicit `robots.txt` allow for GPTBot / ClaudeBot / PerplexityBot / Google-Extended — paste a report URL into any AI and it can read and summarize it without browser tools\n\n```bash\ncd eye\npip install -r requirements.txt\nmake dev  # API (port 8000) + Frontend (port 3000)\n```\n\n### Photo — AI Photo Correction\n\nClaude Code agent for photo editing via Photoshop MCP. Auto-launches Photoshop when needed.\n\n- **Auto-launch**: detects Photoshop state, opens via computer-use if not running\n- **Non-destructive** editing with backup\n- **PIL → Camera Raw → Advanced** priority chain\n- **Over-correction guard**: MAE \u003e 20 triggers parameter reduction\n- No domain-specific config needed\n\n### Sleep — Memory Consolidation\n\nAgent that cleans up Claude Code auto-memory files across all projects.\n\n- **Merge duplicates**, prune stale refs, clean transient notes\n- **Backup first** — timestamped backup with verification before any changes\n- **Dry-run mode** — preview without writing\n- Trigger: say `dream` in Claude Code\n\n```bash\n# Install\ncp sleep/comad-sleep.md ~/.claude/agents/\n```\n\n### Voice — Workflow Automation\n\nClaude Code harness with auto-triggered workflows.\n\n- **6 triggers**: onboarding, review, full-cycle, parallel detection, repo polish, session save\n- **Review Army**: 5 parallel specialist reviewers with adaptive gating\n- **Browser QA**: headless testing for navigation, forms, responsive, performance\n- **Zero dependencies** — pure markdown/bash\n- **Non-developer friendly** — \"just say what you want\"\n\n```bash\n# Install\ncd voice \u0026\u0026 ./install.sh\n```\n\n### Browse — Headless Browser (token-efficient)\n\nPlaywright Chromium wrapper tuned for AI agents. Anti-bot stealth, CLI + HTTP daemon + programmatic API, 23 commands plus 4 dormant ones.\n\n- **@ref interaction**: `snapshot -i` and `find` hand back stable `@e1`, `@e2`... refs instead of long CSS selectors — keeps transcripts compact\n- **Semantic `find`**: filter by `role`/`text`/`label`/`placeholder`/`testid` — refs only, no full snapshot\n- **`batch` stdin JSON**: run N steps (goto → find → fill → click → wait) in one HTTP round-trip\n- **Session persistence**: `--session \u003cname\u003e` auto-saves/loads Playwright `storageState` (cookies, localStorage, IndexedDB) at `.comad/sessions/\u003cname\u003e.json`\n- **Multi-tab**: stable IDs (`t1`, `t2`, …) via `tab list|new|switch|close`\n- **Advanced waits**: `wait selector|text|url|load_state|js` + configurable timeout\n- **Anti-bot stealth**: UA masking, WebDriver flag removal, realistic plugins\n- **Auto-fallback**: brain's content-fetcher uses it when native HTTP returns too little\n- **Dormant features** (implement-ready, off by default — enable with `browse feature enable name=\u003cfeat\u003e`):\n  - `diff` — snapshot/screenshot baseline compare\n  - `har` — request/response buffering + export\n  - `auth` — AES-256-GCM credential vault + auto-login\n  - `route` — network block/mock rules\n\n```bash\ncd browse \u0026\u0026 bun install\nbun run src/cli.ts goto https://example.com\nbun run src/cli.ts find role=button text=Submit   # refs only, no snapshot\nbun run src/cli.ts --session myapp goto https://app.example.com  # persist login\n\n# Batch a login flow in one round-trip\necho '{\"steps\":[\n  {\"command\":\"goto\",\"args\":{\"url\":\"https://app.example.com/login\"}},\n  {\"command\":\"find\",\"args\":{\"role\":\"textbox\",\"placeholder\":\"email\"}},\n  {\"command\":\"fill\",\"args\":{\"selector\":\"@e1\",\"value\":\"me@example.com\"}},\n  {\"command\":\"find\",\"args\":{\"role\":\"button\",\"text\":\"Sign in\"}},\n  {\"command\":\"click\",\"args\":{\"selector\":\"@e2\"}},\n  {\"command\":\"wait\",\"args\":{\"url\":\"**/dashboard\",\"timeout\":10000}}\n]}' | bun run src/cli.ts batch -\n```\n\n### loopy-era — Always-On Self-Evolution Harness\n\nThree LaunchAgents that keep the system measuring, learning, and pruning itself without any user prompt.\n\n- **`com.comad.loopy-era`** — supervisor.py runs a 15-phase tick every 30 minutes; phase 04 promotes T6 patterns into `kb_facts`, phase 15 records a composite score row to `results.tsv`\n- **`com.comad.kb-sleep`** — every 2h: extracts new facts from all `~/.claude/projects/*/memory/*.md`, refreshes Ollama embeddings, runs rule-only consolidation, and publishes the meta-changelog to GitHub Pages\n- **`com.comad.auto-dream`** — daily 03:15 KST: if `dream_pending=true` (memory ≥ 3,500 lines OR ≥ 7 days since last dream), invokes the comad-sleep agent via headless `claude -p` (mutex-guarded against `ccd`/`cdx`)\n- **Single SoT for Claude + Codex** — same 5 `comad_kb_*` MCP tools registered in `comad-brain` server, used identically from `claude`, `ccc`, `ccd`, `cdx`\n- **Live changelog** — every tick publishes meta-only stats (no body content) to \u003chttps://kinkos1234.github.io/memory-log/\u003e\n- **Zero new dependencies** — Python stdlib + local Ollama only\n\n```bash\n# Install (interactive prompt during install.sh)\n./install.sh\n# answer \"y\" to:  Install always-on loopy-era harness (3 LaunchAgents)?\n\n# Manual operations\nloopy-era/bin/supervisor.py status\nloopy-era/bin/start-harness.sh tick\nloopy-era/bin/kb-sleep-tick.py --no-push\n```\n\n### Search — Self-Evolving Reference Discovery\n\nGitHub repo discovery → evaluation → adoption planning → sandbox testing. The system finds patterns to improve itself.\n\n- **Multi-source search**: GitHub, npm, PyPI, and arXiv (papers with code) searched in parallel\n- **3-axis evaluation**: trust (stars/forks/activity), quality (tests/CI/README), relevance (config-driven keywords from `comad.config.yaml`)\n- **Off-topic adoption gate**: hard filter against unrelated domains (genome/finance/game/physics/…) + required overlap with the comad stack (knowledge graph, MCP, Neo4j, agent, LLM, RAG, …)\n- **Neo4j graph storage**: reference cards stored as graph nodes for cross-referencing with brain entities\n- **Adoption planning**: maps discovered patterns to concrete file changes with risk assessment\n- **Sandbox testing**: git worktree isolation for safe verification. `bun install` + `tsc --noEmit` + `bun test` with automatic retry on transient failure\n- **Plan cache**: `--apply N` calls reuse prior `searchAndPlan` output (SHA1-keyed, 1h TTL) so repeated adoption of the same query doesn't re-hit external APIs\n- **Self-supervised learning**: git survival analysis tracks whether adopted patterns survive or get reverted\n- **Ear → /search feed**: nightly cron reads new must-read articles, extracts tech tokens from title+summary, and runs them through the search pipeline\n- **Weekly CRON**: automatic PUSH mode diagnosis every Monday\n- **8 anti-signals**: marketing README, no license, abandoned repos, star manipulation, off-topic domain, missing core-stack match, missing getting-started section, imbalanced star/issue ratio\n\n```bash\ncd brain\nbun run packages/search/src/cli.ts \"knowledge graph MCP\"            # search\nbun run packages/search/src/cli.ts \"RAG pipeline\" --plan             # + adoption plans\nbun run packages/search/src/cli.ts \"MCP server\" --apply 1 --dry-run  # sandbox preview\nbun run packages/search/src/cli.ts --stats                           # health dashboard\n```\n\n---\n\n## Customization\n\n### Quick: Use a Preset\n\n```bash\ncp presets/ai-ml.yaml comad.config.yaml     # AI / Machine Learning\ncp presets/web-dev.yaml comad.config.yaml    # Web Development\ncp presets/finance.yaml comad.config.yaml    # Finance / Fintech\ncp presets/biotech.yaml comad.config.yaml    # Biotech / Life Sciences\n```\n\n### Custom: Edit comad.config.yaml\n\nThe config has 5 sections. Minimal shape (see `presets/*.yaml` for full examples):\n\n```yaml\ninterests:\n  high:   [{ name: \"Core Topic\", keywords: [\"k1\", \"k2\"] }]\n  medium: [{ name: \"Secondary\",  keywords: [\"k3\"] }]\n  low:    [{ name: \"Filter Out\", keywords: [\"noise\"] }]\nsources:\n  rss_feeds: [{ name: \"Blog\", url: \"https://example.com/feed.xml\" }]\n  arxiv:     [{ category: \"cs.CL\", keywords: [\"term\"], max_results: 500 }]\n  github:    { topics: [\"mcp\"], search_queries: [\"knowledge graph\"] }\ncategories: [\"AI/LLM\", \"Tool\", \"OpenSource\"]\nmust_read_stack: [\"Claude Code\", \"Neo4j\", \"Bun\"]\nbrain:\n  entity_extraction:\n    domain_hint: \"one sentence describing your domain\"\n    relationship_types: [\"USES_TECHNOLOGY\", \"COMPETES_WITH\"]\n```\n\n- **`interests`** drives ear relevance + brain filtering.\n- **`sources`** drives brain crawlers.\n- **`categories`** drives ear tagging; **`must_read_stack`** drives ear priority.\n- **`brain.entity_extraction`** drives knowledge modeling in brain.\n\n### Create Your Own Preset\n\n1. Copy an existing preset: `cp presets/ai-ml.yaml presets/my-domain.yaml`\n2. Edit all sections to match your domain\n3. Copy to root: `cp presets/my-domain.yaml comad.config.yaml`\n4. Run `./scripts/apply-config.sh` to regenerate module configs\n\n---\n\n## Presets\n\n| Preset | Domain | RSS Feeds | arXiv Categories | GitHub Topics |\n|--------|--------|:---------:|:----------------:|:-------------:|\n| `ai-ml.yaml` | AI / Machine Learning | 22 | 10 | 20 |\n| `web-dev.yaml` | Web Development | 15 | — | 15 |\n| `finance.yaml` | Finance / Fintech | 10 | 6 | 10 |\n| `biotech.yaml` | Biotech / Life Sciences | 8 | 5 | 10 |\n\nWant to add a preset? PRs welcome.\n\n---\n\n## Project Structure\n\n```\ncomad-world/\n├── comad.config.yaml        # YOUR config (edit this)\n├── presets/                  # Ready-made domain configs\n│   ├── ai-ml.yaml\n│   ├── web-dev.yaml\n│   ├── finance.yaml\n│   └── biotech.yaml\n├── brain/                   # Knowledge graph (Bun/TypeScript)\n│   ├── packages/\n│   │   ├── core/            # Neo4j client, entity extraction, MetaEdge\n│   │   ├── crawler/         # RSS, arXiv, GitHub crawlers (config-driven)\n│   │   ├── graphrag/        # Dual-retriever search engine\n│   │   ├── ingester/        # Content importer\n│   │   ├── mcp-server/      # 20+ MCP tools\n│   │   ├── search/          # Self-evolving reference discovery\n│   │   └── explorer/        # Interactive graph visualization (D3.js)\n│   ├── docker-compose.yml\n│   └── package.json\n├── ear/                     # Content curator (Claude Code agent)\n│   ├── archive/             # Archived articles (YAML frontmatter)\n│   ├── digests/             # Daily digest HTML\n│   └── templates/           # CLAUDE.md + interests.md templates\n├── eye/                     # Simulation engine (Python/FastAPI/Next.js)\n│   ├── api/                 # FastAPI backend\n│   ├── frontend/            # Next.js web UI\n│   ├── config/              # Engine settings\n│   └── ontology/            # Domain-agnostic ontology schema\n├── photo/                   # Photo correction agent\n├── sleep/                   # Memory consolidation agent\n├── voice/                   # Workflow automation harness\n├── scripts/                 # Utility scripts\n│   └── apply-config.sh      # Generate module configs from comad.config.yaml\n├── install.sh               # One-command setup\n└── docker-compose.yml       # Full stack (Neo4j x2 + Ollama)\n```\n\n---\n\n## Requirements\n\n| Component | Required | Optional |\n|-----------|:--------:|:--------:|\n| Claude Code | Yes | — |\n| Docker | Yes (for Neo4j) | — |\n| Bun | Yes (for brain) | — |\n| Python 3.13+ | For eye module | — |\n| Ollama | For eye (local LLM) | — |\n| Adobe Photoshop | For photo module | — |\n| Discord bot | For ear module | — |\n| Codex CLI + tmux | For voice parallel work | — |\n\n---\n\n## FAQ\n\n**Q: Do I need all modules?**\nNo. Each module works independently. Start with `brain` + `ear` for knowledge collection, add others as needed.\n\n**Q: Can I add my own RSS feeds?**\nYes. Edit `sources.rss_feeds` in `comad.config.yaml` and re-run `./scripts/apply-config.sh`.\n\n**Q: Is this only for tech topics?**\nNo. The `finance` and `biotech` presets demonstrate non-tech usage. The system adapts to any domain where there are RSS feeds, papers, and GitHub repos to crawl.\n\n**Q: How much does it cost to run?**\nWith Claude Max subscription, additional cost is $0/day. Brain uses `claude -p --model haiku` (included in Max). Eye uses local Ollama (free). No external API calls.\n\n**Q: Can I contribute a preset for my domain?**\nYes! See [CONTRIBUTING.md](CONTRIBUTING.md).\n\n---\n\n## Credits\n\nBuilt with [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and the [Model Context Protocol](https://modelcontextprotocol.io/).\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for all notable changes.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkinkos1234%2Fcomad-world","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkinkos1234%2Fcomad-world","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkinkos1234%2Fcomad-world/lists"}