📯 Agentara

Meet 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.

Features

• Agent-powered sessions — Interact with Claude Code and OpenAI Codex through managed sessions with full streaming support
• Multi-channel messaging — Receive and respond to messages from multiple channels (e.g. Feishu/Lark)
• Message streaming — Streaming response for IM channel (if supported message updating/patching, e.g. Feishu)
• Task scheduling — Queue-based task dispatcher with per-session serial execution and cross-session concurrency
• Cron jobs — Schedule recurring tasks with cron patterns
• Session persistence — Sessions stored as JSONL files with full message history
• Web dashboard — React-based UI for managing sessions, tasks, and memory
• File and image support — Send and receive files and images through message channels
• RESTful API — Hono-based API server with type-safe RPC client

Built-in Skills

• amap
• claude-usage
• consulting-analysis
• current-time
• daily-hunt
• data-analysis
• deep-research
• find-skills
• fix-my-life
• frontend-design
• github-deep-research
• heartbeat
• image-generation
• ppt-generation
• pulse
• scheduled-tasks
• skill-creator
• stock
• technical-writing-skill
• vercel-deploy-claimable
• weather-report
• web-design-guidelines

Tech Stack

Backend

Category	Technology
Runtime	Bun
Language	TypeScript
API	Hono
Database	SQLite (Bun built-in) + Drizzle ORM
Task Queue	Bunqueue
Validation	Zod
Logging	Pino
Date	Day.js
Events	EventEmitter3

Frontend

Category	Technology
Framework	React 19 + Vite 7
Routing	TanStack Router
Data Fetching	TanStack React Query
Styling	Tailwind CSS v4 + Shadcn
Theme	Dark mode by default

Prerequisites

• Bun (latest)
• One of the following coding agents:
  • Claude Code installed and configured
  • OpenAI Codex installed and configured

Quick Start

First, clone the repo and install all its dependencies.

git clone https://github.com/magiccube/agentara.git
cd agentara
make install

Then, run in DEVELOPMENT mode. Both backend server and frontend website will be launched.

make dev

On first run, Agentara creates ~/.agentara with default config, workspace, and data directories.

The backend runs on http://localhost:1984 and the frontend dev server on http://localhost:8000 (proxying API requests to the backend).

Go to your IM client and start chatting with Tara:

/bootstrap

Or schedule a cronjob:

Hey, Tara! Schedule a cronjob to run every 7:30 AM and 5:30 PM to run the `/pulse` skill.

Configuration

Environment Variables

Variable	Description	Default
AGENTARA_HOME	Home directory for all Agentara data	~/.agentara
AGENTARA_LOG_LEVEL	Log level (trace, debug, info, warn, error)	info
AGENTARA_SERVICE_PORT	API server port	1984
AGENTARA_SERVICE_HOST	API server host	localhost

Config File

A config.yaml is auto-generated at $AGENTARA_HOME/config.yaml on first run. Here is an example:

agents:
  default:
    type: claude          # Agent runner to use

tasking:
  max_retries: 1          # Max attempts per task before marking as failed

messaging:
  default_channel_id: 9e3eae94-fe88-4043-af40-e7f88943a370  # Change it to yours
  channels:
    - id: 9e3eae94-fe88-4043-af40-e7f88943a370 # Unique ID for the channel
      type: feishu
      name: Tara
      description: Tara's default channel
      params:
        app_id: $FEISHU_APP_ID       # Resolved from environment variable
        app_secret: $FEISHU_APP_SECRET
        chat_id: oc_xxxxxxxxxxxxx

String 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.

Directory Structure

All data lives under $AGENTARA_HOME (~/.agentara by default):

~/.agentara/
├── config.yaml       # Configuration file
├── workspace/        # Agent workspace
├── sessions/         # Session JSONL files
├── memory/           # Agent memory
└── data/             # SQLite databases

Architecture Overview

Project Structure

src/
├── shared/           # Cross-layer types, utilities, conventions
│   ├── agents/       # AgentRunner interface
│   ├── messaging/    # Message types, channels, gateway
│   ├── tasking/      # Task payload types
│   ├── sessioning/   # Session types
│   ├── config/       # Paths and configuration
│   ├── logging/      # Pino logger
│   └── utils/        # Pure utilities
├── kernel/           # Core orchestration
│   ├── agents/       # Agent runner factory
│   ├── sessioning/   # Session, SessionManager
│   ├── tasking/      # TaskDispatcher (Bunqueue)
│   └── messaging/    # Multi-channel message gateway
├── community/        # Provider implementations
│   ├── anthropic/    # Claude agent runner
│   └── feishu/       # Feishu/Lark messaging channel
├── server/           # Hono API server
├── data/             # Database connection
└── boot-loader/      # Bootstrap and integrity verification
web/                  # React frontend (separate package)

Scripts

Command	Description
bun run dev	Start backend and frontend in dev mode
bun run dev:server	Start backend only
bun run dev:web	Start frontend only
bun run check	Type-check and lint
bun run build:bin	Compile to a standalone binary
bun run build:js	Build JS bundle

Contributing

Contributions are welcome! Here's how to get started:

1. Fork the repository
2. Create a branch for your feature or fix: git checkout -b feat/my-feature
3. Install dependencies: bun install
4. Make your changes and ensure they pass checks:

   bun run check    # Type-check + lint

5. Commit with a clear message following Conventional Commits:
   • feat: for new features
   • fix: for bug fixes
   • chore: for maintenance
   • docs: for documentation
6. Open a Pull Request against main

Code Conventions

• Use logger from @/shared for logging — never use console.log directly
• Import from @/shared directly, not from sub-paths
• Entities are defined with Zod schemas first, TypeScript interfaces second
• Use underscore naming for entity fields
• Private class members are prefixed with _
• Provide TSDoc for all public APIs

License

MIT