A Rust-based multi-agent system featuring a mail system, CRON schedules, and Zettelkasten-style knowledge base with Markdown support.
Features
- Runs on PostgreSQL: the best db ;)
- Multi-Agent System: Create and manage agents with status tracking
- Mail System: Agents can send and receive messages via mailboxes
- CRON Schedules: Schedule recurring tasks with automatic triggering — agents can manage their own schedules via CLI or web interface
- Knowledge Base: Zettelkasten-style notes with Markdown support and Luhmann addressing (1, 1a, 1a1)
- Web Interface: HTMX-based UI for browsing agents, mail, schedules, and knowledge base
- Onboarding: Built-in guide for new AI agents with
how-we-workcommand
Important Design Notes:
- Private conversations are not supported — all mail is processed within the same session
- Private schedules are not supported — all agents share the same schedule execution context
- All agents process mail and schedules in the same session — there is no isolation between agents
- No authentication or authorization — the web interface is wide open; any user can send messages to any agent, view all mail, and manage all schedules
- This is typically not an issue because this application is designed to run on a local LAN for a single person or small trusted team. The shared session model and lack of access controls simplify the architecture and are appropriate for personal or small-scale use cases.
Quick Start
# Set up database (human-only), PLEASE JUST PUT THIS IN A .env file in your work directory agents will run. Will make things simpler.
# Register agents
# Send mail
# Start web server (human-only)
# For new agents: learn how to work
Running an Agent Office with Opencode
Agent Office works best when paired with an AI coding assistant like Opencode. Here's how to set up an integrated workflow:
1. Create Your Human Agent First
Before creating your AI assistant, create an agent to represent yourself first ;)
# Register yourself as an agent (set status to "human" for fun!)
2. Create an Agent Descriptor in Opencode
Now create your AI assistant. First, create an agent configuration file in your Opencode config directory:
# Create the agent descriptor file
you can specify your model in here too! look at https://opencode.ai/docs/agents/
3. Start an Opencode Session
Start Opencode with your agent and note the session ID:
# Start opencode in the folder you want it to run ( this breifly runs opencode just long enough to get a seession id )
|
# The session ID will be displayed (e.g., ses_abc123def456)
# Note this down - you'll need it for the next step
4. Register the Agent in Agent Office
Create the agent in Agent Office and link it to your Opencode session:
# Register the agent
# Set the session ID to match your opencode session
# Use the format: ses_<your-opencode-session-id>
5. Run the Agent
Start the agent runner to automatically trigger your Opencode agent when mail or schedules arrive:
# Run the agent - it will use the configured session ID to check for mail and cron job every 60 seconds
6. Start the Web Interface
Open a new terminal tab and start the web interface:
# Start the web server
# Visit http://127.0.0.1:8080 to see the dashboard
7. Send a Message
Now you can send messages to your agent through the web interface:
- Open your browser to
http://127.0.0.1:8080 - Find your AI agent on the dashboard
- Click 📥 Inbox for the AI agent
- Use the "Send Message to Agent" form
- Fill in:
- To:
myagent(your AI agent's name) - From:
richard(your human agent name) - Subject:
Hello! - Message:
Please review the codebase and refactor the error handling
- To:
- Click Send Message
The AI agent will receive the message and automatically trigger (if running, remember it might take up to 60 seconds) to process it!
8. Set Up a Schedule (Optional)
You can either manually create a schedule through the web interface or ask your AI agent to do it:
Option A: Manual Setup via Web Interface
- On the dashboard, find your AI agent
- Click ⏰ Schedules button
- Click New Schedule
- Fill in:
- CRON Expression:
0 9 * * *(daily at 9am) or*/5 * * * *(every 5 minutes for testing) - Action:
Generate daily reportorCheck system status
- CRON Expression:
- Click Create Schedule
Option B: Ask Your AI Agent to Create It
Send a message asking the agent to create a schedule:
- Go to the AI agent's inbox
- Send a new message:
- To:
myagent - From:
richard - Subject:
Please create a daily schedule - Message:
Please create a schedule that runs every day at 9am with the action "Generate daily summary report". Use the command: agent-office schedule create myagent "0 9 * * *" "Generate daily summary report"
- To:
The AI agent will process the message and create the schedule for you!
Environment Variables: When the bash command is executed, two environment variables are set:
AGENT_OFFICE_SESSION: The session ID from your agent's configuration (e.g.,ses_abc123def456). This ensures all work happens in the same Opencode session for consistent context and state.AGENT_OFFICE_EVENT: A description of what triggered the execution:- For mail:
agent id "myagent" has unread mail - For schedules:
agent id "myagent" received a scheduled action request "action description"
- For mail:
Important: Always use single quotes around the bash command to prevent your shell from expanding environment variables before they reach the agent.
Managing Agent Session IDs
The session ID links your Agent Office agent to a specific Opencode session. This ensures:
- Consistent context across multiple triggers
- Persistent state between executions
- Proper tracking of which agent performed which action
# View current session ID for an agent
# Change the session ID (e.g., when starting a new opencode session)
# Clear the custom session (will use agent ID as fallback)
# View and edit session IDs via web interface at http://127.0.0.1:8080
⏰ Managing Schedules
CRON schedules allow agents to be automatically triggered at specific times (e.g., daily reports, periodic health checks):
# Create a daily schedule for an agent
# Create a schedule that fires every 5 minutes
# List all schedules for an agent
# Get details of a specific schedule
# Update a schedule (change CRON or action)
# Toggle schedule on/off
# Delete a schedule
CRON Format: minute hour day month weekday (e.g., 0 9 * * * = daily at 9am, */5 * * * * = every 5 minutes)
Web UI: Visit /agents/{agent_id}/schedule to manage schedules visually with last run tracking.
Agent Configuration: Create your agent at ~/.config/opencode/agents/my-agent.md with full permissions using YAML front matter:
description: Autonomous agent for Agent Office system
mode: primary
permission:
bash:
edit: allow
write: allow
read: allow
external_directory:
webfetch: allow
websearch: allow
task: allow
Your agent ID is: my-agent
The first thing you should do is execute `agent-office how-we-work` to understand how we work.
This enables fully autonomous agent workflows where your AI agent:
- Waits for incoming messages
- Automatically processes them when they arrive
- Can respond, take actions, or escalate as needed
Configuration
Set AGENT_OFFICE_URL environment variable or use .env file in the folder your agentic coding CLI runs:
AGENT_OFFICE_URL=postgresql://agent:agent123@localhost:5432/agent_office
Options
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
Web Interface
Visit http://127.0.0.1:8080 to:
- View all agents and their status
- Browse agent inboxes and outboxes with message subjects
- Manage CRON schedules for each agent with last run tracking
- Browse the knowledge base with Markdown rendering
- Set agents offline with one click
- Edit agent session IDs for consistent bash execution tracking
- Mobile-friendly responsive design
Acknowledgements
This project was inspired by and built for Opencode (formerly OpenCode). The concept of AI agents working alongside humans in a collaborative "office" environment directly stems from the vision of making AI assistants first-class team members. Thank you to the Opencode team for pioneering this space and creating the infrastructure that makes Agent Office possible.
License
MIT