{"id":49535206,"url":"https://github.com/karryviber/orb","last_synced_at":"2026-05-02T10:02:35.549Z","repository":{"id":351924418,"uuid":"1212187194","full_name":"KarryViber/Orb","owner":"KarryViber","description":"Self-evolving AI agent framework — wraps Claude Code CLI with persistent memory, multi-profile isolation, and messaging platform integration","archived":false,"fork":false,"pushed_at":"2026-04-25T04:03:12.000Z","size":2537,"stargazers_count":53,"open_issues_count":0,"forks_count":7,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-25T06:11:52.891Z","etag":null,"topics":["ai-agent","claude","claude-code","memory","multi-profile","slack-bot"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/KarryViber.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"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-16T06:27:28.000Z","updated_at":"2026-04-25T04:03:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/KarryViber/Orb","commit_stats":null,"previous_names":["karryviber/orb"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/KarryViber/Orb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KarryViber%2FOrb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KarryViber%2FOrb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KarryViber%2FOrb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KarryViber%2FOrb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KarryViber","download_url":"https://codeload.github.com/KarryViber/Orb/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KarryViber%2FOrb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32530176,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T01:12:54.858Z","status":"online","status_checked_at":"2026-05-02T02:00:05.923Z","response_time":132,"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-agent","claude","claude-code","memory","multi-profile","slack-bot"],"created_at":"2026-05-02T10:02:28.881Z","updated_at":"2026-05-02T10:02:35.541Z","avatar_url":"https://github.com/KarryViber.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/orb-logo.png\" alt=\"Orb\" width=\"160\" /\u003e\n\u003c/p\u003e\n\n# Orb\n\n\u003e A multi-profile messaging shell around Claude Code CLI.\n\n## What Orb Is\n\nOrb receives messages from a platform adapter, routes them to the right profile, starts or resumes a per-thread Claude Code CLI session, and sends the result back. Orb does not replace Claude Code's runtime. It supplies routing, profile isolation, long-term recall, document search, cron execution, and approval handling around the native CLI.\n\n```text\nYou (Slack DM / thread)\n        |\n        v\n      Orb\n        |\n        v\nClaude Code CLI (one worker per thread, cwd = profiles/{name}/workspace/)\n        |\n        v\n      Reply\n```\n\n## Why Claude Code Native\n\n- Claude Code already auto-discovers `CLAUDE.md`, workspace skills, workspace agents, and CLI-managed memory from the current working directory.\n- Orb stays outside the agent runtime. It handles message routing, context assembly, profile boundaries, cron orchestration, and permission relay.\n- Claude Code upgrades land without a prompt-stack migration inside Orb.\n- The worker process talks to Claude Code over native `stream-json`, so Orb can reuse sessions for follow-up turns in the same thread instead of rebuilding an agent loop of its own.\n\n## Features\n\n- Multi-profile isolation with separate `scripts/`, `workspace/`, and `data/` directories per profile.\n- Slack Socket Mode adapter for production use, with adapter boundaries that keep new platforms isolated.\n- Holographic long-term memory in local SQLite for fact extraction, trust scoring, decay controls, and write-time arbitration.\n- DocStore full-text search in local SQLite FTS5, with project slug inference from the thread and registry-driven path mapping.\n- Cron scheduling with per-profile `cron-jobs.json`, fire-and-forget workers, and per-job inflight guards.\n- MCP permission relay that can surface Claude Code approval requests in Slack.\n- Short-lived per-thread workers that reuse the same Claude session for follow-up messages via `inject` IPC.\n\n## Quickstart\n\nPrerequisites:\n\n- Node.js 18 or newer\n- Python 3.11 or newer\n- Claude Code CLI installed and authenticated\n- A Slack app with Socket Mode enabled\n\nInstall and start:\n\n```bash\ngit clone https://github.com/KarryViber/Orb.git\ncd Orb\nnpm install\ncp .env.example .env\ncp config.example.json config.json\n```\n\nCreate your first profile:\n\n```bash\nmkdir -p profiles/alice/scripts\nmkdir -p profiles/alice/workspace/.claude/skills\nmkdir -p profiles/alice/data\ncp profiles/example/workspace/CLAUDE.md profiles/alice/workspace/CLAUDE.md\n```\n\nFill in `.env` and `config.json`, then start Orb:\n\n```bash\nnpm start\n```\n\nSend the Slack bot a DM. If routing, Claude authentication, and Socket Mode are all correct, Orb will start a worker for that thread and return the reply in Slack.\n\nThe full walkthrough lives in [docs/getting-started.md](docs/getting-started.md).\n\n## Architecture At A Glance\n\n```text\nsrc/main.js\n   |\n   +--\u003e adapters/* ------------------------------+\n   |                                             |\n   +--\u003e src/cron.js                              |\n   |        |                                    |\n   |        +--\u003e spawn cron worker --------------+\n   |                                             |\n   +--\u003e src/scheduler.js \u003c---- unix socket ---- src/mcp-permission-server.js\n              |                                       ^\n              |                                       |\n              +--\u003e fork src/worker.js per thread -----+\n                        |\n                        +--\u003e Claude Code CLI\n                        |      cwd = profiles/{name}/workspace/\n                        |      auto-discovers:\n                        |      - ~/.claude/CLAUDE.md\n                        |      - ./CLAUDE.md\n                        |      - workspace/CLAUDE.md\n                        |      - workspace/.claude/skills/\n                        |      - workspace/.claude/agents/\n                        |      - CLI-managed memory\n                        |\n                        +--\u003e sidecars\n                               - lib/holographic/*  -\u003e memory.db\n                               - lib/docstore/*     -\u003e doc-index.db\n```\n\nThe deeper walkthrough is in [docs/architecture.md](docs/architecture.md).\n\n## Prompt Architecture\n\nClaude Code discovers the stable layers natively:\n\n- Layer 1: `~/.claude/CLAUDE.md`\n- Layer 2: repository-root `CLAUDE.md`\n- Layer 3: `profiles/{name}/workspace/CLAUDE.md`\n- Workspace add-ons: `profiles/{name}/workspace/.claude/skills/` and `profiles/{name}/workspace/.claude/agents/`\n- System-scope skills shared across profiles: repository-root `.claude/skills/` (loaded into every worker via `--add-dir`)\n- CLI-managed memory tied to the workspace `cwd`\n\nOrb only adds what the CLI does not already know:\n\n- A minimal appended system prompt with the profile's `scripts/` path\n- Holographic memory recall from `profiles/{name}/data/memory.db`\n- DocStore recall from `profiles/{name}/data/doc-index.db`\n- Thread history supplied by the adapter\n- Thread metadata, file text, and the current user message\n\n## Memory Subsystems\n\nOrb uses two memory tracks plus document recall:\n\n- Holographic memory: a local fact store in `profiles/{name}/data/memory.db`, used for extraction, trust-weighted recall, contradiction handling, and memory hygiene jobs.\n- Claude Code auto-memory: the CLI's own persistent memory store, keyed by the profile workspace path under `~/.claude/projects/\u003cencoded-cwd\u003e/memory/`.\n- DocStore: a separate file index in `profiles/{name}/data/doc-index.db` with FTS5 search and project slug scoping.\n\nThe important split is architectural: Orb owns cross-thread factual recall and document lookup, while Claude Code owns its native persistent memory for the workspace.\n\n## Cron\n\nEach profile can keep scheduled jobs in `profiles/{name}/data/cron-jobs.json`. The cron scheduler reads the file, computes due runs, forks a worker, and optionally delivers the result back through an adapter.\n\nExample job:\n\n```json\n{\n  \"id\": \"daily-report\",\n  \"name\": \"Daily Report\",\n  \"prompt\": \"Summarize today's open work items.\",\n  \"schedule\": {\n    \"kind\": \"cron\",\n    \"expr\": \"0 9 * * *\",\n    \"display\": \"0 9 * * *\"\n  },\n  \"deliver\": {\n    \"platform\": \"slack\",\n    \"channel\": \"C0123456789\",\n    \"threadTs\": null\n  },\n  \"profileName\": \"alice\",\n  \"enabled\": true,\n  \"model\": \"haiku\",\n  \"effort\": \"low\"\n}\n```\n\nSuggested model tiers:\n\n| Task type | Model | Effort |\n| --- | --- | --- |\n| Scripted or templated output | `haiku` | `low` |\n| Summaries and routine aggregation | `sonnet` | `medium` |\n| Decision review or knowledge distillation | `sonnet` | `high` |\n| Deep analysis | `opus` | `xhigh` |\n\n## Permission Model\n\nWhen Claude Code requests approval for an action outside the worker's default allowlist, Orb can relay that request through an MCP permission tool:\n\n- The worker writes a temporary MCP config and starts Claude Code with `--permission-prompt-tool`.\n- `src/mcp-permission-server.js` forwards the request over a Unix socket to `src/scheduler.js`.\n- The scheduler either auto-allows or sends an approval card through the active adapter.\n- Slack is the implemented interactive approval route today.\n\nOrb also seeds `profiles/{name}/workspace/.claude/settings.json` on demand with a conservative allowlist for common read-only and inspection commands.\n\n## Profiles\n\nA profile is a complete Claude working environment:\n\n```text\nprofiles/{name}/\n├── scripts/\n├── workspace/\n│   ├── CLAUDE.md\n│   └── .claude/\n│       ├── skills/\n│       └── agents/\n└── data/\n    ├── sessions.json\n    ├── memory.db\n    ├── doc-index.db\n    └── cron-jobs.json\n```\n\nSee [docs/profile-guide.md](docs/profile-guide.md) for the full profile model.\n\n## Adding A Platform\n\nNew platforms plug in through the `PlatformAdapter` interface in `src/adapters/interface.js`. Orb keeps formatting, transport, and approval handling behind the adapter boundary so scheduler and worker code do not need platform-specific imports.\n\nSee [docs/adapter-development.md](docs/adapter-development.md).\n\n## Project Layout\n\n```text\nsrc/\n├── main.js                # adapter startup, scheduler, signals\n├── scheduler.js           # worker lifecycle, queueing, approvals\n├── worker.js              # Claude CLI session management\n├── cron.js                # scheduled jobs\n├── context.js             # Orb-managed prompt additions (delegates to providers)\n├── context-providers/     # holographic / docstore / thread-history / skill-review\n├── turn-delivery/         # per-turn delivery orchestration (intents, ledger, status, streams)\n├── memory.js              # holographic + docstore bridges\n├── session.js             # thread -\u003e Claude session persistence\n├── ipc-schema.js          # worker \u003c-\u003e scheduler IPC payload schema\n├── stop-reason.js         # unified stopReason classification\n├── format-utils.js        # adapter-agnostic text helpers\n└── adapters/\n    ├── interface.js\n    ├── slack.js\n    ├── slack-format.js\n    ├── slack-permission-render.js\n    ├── slack-stream-error.js\n    ├── slack-block-actions.js\n    └── slack-dm-routing.js\n\nlib/\n├── holographic/           # Python memory bridge and maintenance\n├── docstore/              # Python FTS5 index and search bridge\n├── lesson-distill/        # lesson candidate distillation\n└── memory-usage/          # memory usage tracking + decay\n\nscripts/\n├── cron/                  # cron-deliver, channel resolve, run log\n├── slack/                 # blockkit, send-thread, send-attachment, extract\n├── wechat/                # WeChat helpers\n├── infra/                 # backup, hardware monitor, mac health, outbound gate\n├── workflow/              # claudemd-lint, external-session-spawn, memory-crud\n└── hooks/                 # PreToolUse / docstore hint hooks\n\n.claude/\n└── skills/                # system-scope skills shared across profiles\n\nprofiles/\n└── {name}/                # scripts + workspace + data\n```\n\n## Status\n\n- Slack adapter: production path\n- WeChat adapter: in-repo but not documented here as a primary deployment target\n- Discord: not implemented\n- Other platforms: contributions welcome\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkarryviber%2Forb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkarryviber%2Forb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkarryviber%2Forb/lists"}