{"id":50521928,"url":"https://github.com/MagicCube/agentara","last_synced_at":"2026-06-19T23:00:38.777Z","repository":{"id":344152665,"uuid":"1173307371","full_name":"MagicCube/agentara","owner":"MagicCube","description":"Your 24/7 personal assistant powered by Claude Code and OpenAI Codex. Multi-channel messaging, long-term memory, skills, task scheduling, session management, and more — all running locally.","archived":false,"fork":false,"pushed_at":"2026-05-06T03:11:37.000Z","size":3316,"stargazers_count":366,"open_issues_count":0,"forks_count":39,"subscribers_count":6,"default_branch":"main","last_synced_at":"2026-05-06T05:12:39.724Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MagicCube.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-03-05T08:16:37.000Z","updated_at":"2026-05-06T03:11:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/MagicCube/agentara","commit_stats":null,"previous_names":["magiccube/agentara"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/MagicCube/agentara","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MagicCube%2Fagentara","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MagicCube%2Fagentara/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MagicCube%2Fagentara/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MagicCube%2Fagentara/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MagicCube","download_url":"https://codeload.github.com/MagicCube/agentara/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MagicCube%2Fagentara/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34550858,"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-19T02:00:06.005Z","response_time":61,"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":[],"created_at":"2026-06-03T05:00:34.616Z","updated_at":"2026-06-19T23:00:38.768Z","avatar_url":"https://github.com/MagicCube.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# 📯 Agentara\n\n[![CI](https://github.com/MagicCube/agentara/actions/workflows/ci.yml/badge.svg)](https://github.com/MagicCube/agentara/actions/workflows/ci.yml)\n[![Test](https://github.com/MagicCube/agentara/actions/workflows/test.yml/badge.svg)](https://github.com/MagicCube/agentara/actions/workflows/test.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Bun](https://img.shields.io/badge/runtime-Bun-f9f1e1?logo=bun)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5-blue?logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org)\n[![Hono](https://img.shields.io/badge/API-Hono-E36002?logo=hono\u0026logoColor=white)](https://hono.dev)\n[![React](https://img.shields.io/badge/Frontend-React_19-61DAFB?logo=react\u0026logoColor=white)](https://react.dev)\n\n\u003cimg width=\"1916\" height=\"821\" alt=\"ADF7F867-88A5-4623-B5A9-06D1CDF4C28E_1_201_a 1\" src=\"https://github.com/user-attachments/assets/ea8b312a-4631-410b-8649-6ed522d3e9b4\" /\u003e\n\nMeet Tara, your 24/7 personal assistant powered by Claude Code and OpenAI Codex. Multi-channel messaging, long-term memory, skills, task scheduling, session management, and more — all running locally.\n\n## Features\n\n- **Agent-powered sessions** — Interact with Claude Code and OpenAI Codex through managed sessions with full streaming support\n- **Multi-channel messaging** — Receive and respond to messages from multiple channels (e.g. Feishu/Lark)\n- **Message streaming** — Streaming response for IM channel (if supported message updating/patching, e.g. Feishu)\n- **Task scheduling** — Queue-based task dispatcher with per-session serial execution and cross-session concurrency\n- **Cron jobs** — Schedule recurring tasks with cron patterns\n- **Session persistence** — Sessions stored as JSONL files with full message history\n- **Web dashboard** — React-based UI for managing sessions, tasks, and memory\n- **File and image support** — Send and receive files and images through message channels\n- **RESTful API** — Hono-based API server with type-safe RPC client\n\n## Built-in Skills\n\n- [amap](user-home/.claude/skills/amap)\n- [claude-usage](user-home/.claude/skills/claude-usage)\n- [consulting-analysis](user-home/.claude/skills/consulting-analysis)\n- [current-time](user-home/.claude/skills/current-time)\n- [daily-hunt](user-home/.claude/skills/daily-hunt)\n- [data-analysis](user-home/.claude/skills/data-analysis)\n- [deep-research](user-home/.claude/skills/deep-research)\n- [find-skills](user-home/.claude/skills/find-skills)\n- [fix-my-life](user-home/.claude/skills/fix-my-life)\n- [frontend-design](user-home/.claude/skills/frontend-design)\n- [github-deep-research](user-home/.claude/skills/github-deep-research)\n- [heartbeat](user-home/.claude/skills/heartbeat)\n- [image-generation](user-home/.claude/skills/image-generation)\n- [ppt-generation](user-home/.claude/skills/ppt-generation)\n- [pulse](user-home/.claude/skills/pulse)\n- [scheduled-tasks](user-home/.claude/skills/scheduled-tasks)\n- [skill-creator](user-home/.claude/skills/skill-creator)\n- [stock](user-home/.claude/skills/stock)\n- [technical-writing-skill](user-home/.claude/skills/technical-writing-skill)\n- [vercel-deploy-claimable](user-home/.claude/skills/vercel-deploy-claimable)\n- [weather-report](user-home/.claude/skills/weather-report)\n- [web-design-guidelines](user-home/.claude/skills/web-design-guidelines)\n\n## Tech Stack\n\n**Backend**\n\n| Category | Technology |\n|----------|------------|\n| Runtime | [Bun](https://bun.sh) |\n| Language | TypeScript |\n| API | [Hono](https://hono.dev) |\n| Database | SQLite (Bun built-in) + [Drizzle ORM](https://orm.drizzle.team) |\n| Task Queue | [Bunqueue](https://github.com/nicexlab/bunqueue) |\n| Validation | [Zod](https://zod.dev) |\n| Logging | [Pino](https://getpino.io) |\n| Date | [Day.js](https://day.js.org) |\n| Events | [EventEmitter3](https://github.com/primus/eventemitter3) |\n\n**Frontend**\n\n| Category | Technology |\n|----------|------------|\n| Framework | React 19 + Vite 7 |\n| Routing | TanStack Router |\n| Data Fetching | TanStack React Query |\n| Styling | Tailwind CSS v4 + [Shadcn](https://ui.shadcn.com) |\n| Theme | Dark mode by default |\n\n## Prerequisites\n\n- [Bun](https://bun.sh) (latest)\n- One of the following coding agents:\n  - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed and configured\n  - [OpenAI Codex](https://openai.com/api/codex/) installed and configured\n\n## Quick Start\n\nFirst, clone the repo and install all its dependencies.\n\n```bash\ngit clone https://github.com/magiccube/agentara.git\ncd agentara\nmake install\n```\n\nThen, run in DEVELOPMENT mode. Both backend server and frontend website will be launched.\n\n```bash\nmake dev\n```\n\nOn first run, Agentara creates `~/.agentara` with default config, workspace, and data directories.\n\nThe backend runs on `http://localhost:1984` and the frontend dev server on `http://localhost:8000` (proxying API requests to the backend).\n\nGo to your IM client and start chatting with Tara:\n\n```\n/bootstrap\n```\n\nOr schedule a cronjob:\n\n```\nHey, Tara! Schedule a cronjob to run every 7:30 AM and 5:30 PM to run the `/pulse` skill.\n```\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `AGENTARA_HOME` | Home directory for all Agentara data | `~/.agentara` |\n| `AGENTARA_LOG_LEVEL` | Log level (`trace`, `debug`, `info`, `warn`, `error`) | `info` |\n| `AGENTARA_SERVICE_PORT` | API server port | `1984` |\n| `AGENTARA_SERVICE_HOST` | API server host | `localhost` |\n\n### Config File\n\nA `config.yaml` is auto-generated at `$AGENTARA_HOME/config.yaml` on first run. Here is an example:\n\n```yaml\nagents:\n  default:\n    type: claude          # Agent runner to use\n\ntasking:\n  max_retries: 1          # Max attempts per task before marking as failed\n\nmessaging:\n  default_channel_id: 9e3eae94-fe88-4043-af40-e7f88943a370  # Change it to yours\n  channels:\n    - id: 9e3eae94-fe88-4043-af40-e7f88943a370 # Unique ID for the channel\n      type: feishu\n      name: Tara\n      description: Tara's default channel\n      params:\n        app_id: $FEISHU_APP_ID       # Resolved from environment variable\n        app_secret: $FEISHU_APP_SECRET\n        chat_id: oc_xxxxxxxxxxxxx\n```\n\nString values starting with `$` are automatically resolved from environment variables at load time. All fields are validated with Zod on startup — missing or invalid values will produce a clear error.\n\n### Directory Structure\n\nAll data lives under `$AGENTARA_HOME` (`~/.agentara` by default):\n\n```\n~/.agentara/\n├── config.yaml       # Configuration file\n├── workspace/        # Agent workspace\n├── sessions/         # Session JSONL files\n├── memory/           # Agent memory\n└── data/             # SQLite databases\n```\n\n## Architecture Overview\n\n![architecture](https://github.com/user-attachments/assets/ecd7a64d-2191-48ec-bb2e-cda577d24d1f)\n\n\n## Project Structure\n\n```\nsrc/\n├── shared/           # Cross-layer types, utilities, conventions\n│   ├── agents/       # AgentRunner interface\n│   ├── messaging/    # Message types, channels, gateway\n│   ├── tasking/      # Task payload types\n│   ├── sessioning/   # Session types\n│   ├── config/       # Paths and configuration\n│   ├── logging/      # Pino logger\n│   └── utils/        # Pure utilities\n├── kernel/           # Core orchestration\n│   ├── agents/       # Agent runner factory\n│   ├── sessioning/   # Session, SessionManager\n│   ├── tasking/      # TaskDispatcher (Bunqueue)\n│   └── messaging/    # Multi-channel message gateway\n├── community/        # Provider implementations\n│   ├── anthropic/    # Claude agent runner\n│   └── feishu/       # Feishu/Lark messaging channel\n├── server/           # Hono API server\n├── data/             # Database connection\n└── boot-loader/      # Bootstrap and integrity verification\nweb/                  # React frontend (separate package)\n```\n\n## Scripts\n\n| Command | Description |\n|---------|-------------|\n| `bun run dev` | Start backend and frontend in dev mode |\n| `bun run dev:server` | Start backend only |\n| `bun run dev:web` | Start frontend only |\n| `bun run check` | Type-check and lint |\n| `bun run build:bin` | Compile to a standalone binary |\n| `bun run build:js` | Build JS bundle |\n\n## Contributing\n\nContributions are welcome! Here's how to get started:\n\n1. **Fork** the repository\n2. **Create a branch** for your feature or fix: `git checkout -b feat/my-feature`\n3. **Install dependencies**: `bun install`\n4. **Make your changes** and ensure they pass checks:\n   ```bash\n   bun run check    # Type-check + lint\n   ```\n5. **Commit** with a clear message following [Conventional Commits](https://www.conventionalcommits.org):\n   - `feat:` for new features\n   - `fix:` for bug fixes\n   - `chore:` for maintenance\n   - `docs:` for documentation\n6. **Open a Pull Request** against `main`\n\n### Code Conventions\n\n- Use `logger` from `@/shared` for logging — never use `console.log` directly\n- Import from `@/shared` directly, not from sub-paths\n- Entities are defined with Zod schemas first, TypeScript interfaces second\n- Use underscore naming for entity fields\n- Private class members are prefixed with `_`\n- Provide TSDoc for all public APIs\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMagicCube%2Fagentara","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMagicCube%2Fagentara","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMagicCube%2Fagentara/lists"}