📯 Agentara

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

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

architecture

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:

Fork the repository
Create a branch for your feature or fix: git checkout -b feat/my-feature
Install dependencies: bun install
Make your changes and ensure they pass checks:
```
bun run check    # Type-check + lint
```
Commit with a clear message following Conventional Commits:
- feat: for new features
- fix: for bug fixes
- chore: for maintenance
- docs: for documentation
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

Agentara

Install / Use

README