Compass

Compass is an AI chief of staff for startups. It listens to your Telegram conversations, extracts tasks, decisions, blockers, and commitments, stores them in structured files, and posts clear summaries to Slack — automatically.

Compass is not a chatbot. It is your execution memory and reporting layer.

Built on OpenClaw.

What Compass does

| Capability | Detail | |---|---| | Listens to Telegram | Reads group and DM conversations passively | | Extracts signal | Tasks, decisions, blockers, commitments, metrics | | Maintains memory | Writes structured state to local files | | Answers questions | Responds when mentioned directly (@Compass) | | Posts to Slack | Daily standups and weekly reviews on schedule | | Stays quiet | Silent unless mentioned or scheduled |

Prerequisites

| Requirement | Detail | |---|---| | Linux (Ubuntu 20.04+ / Debian 11+) | Cron and service management require Linux | | Node.js 18 or higher | Runtime | | Telegram bot token | From @BotFather | | Your Telegram user ID | From @userinfobot | | Slack bot token | From your Slack app settings (starts with xoxb-) | | LLM API key | Anthropic or OpenAI |

Installation

npm install -g compass-ai

Setup (run once)

compass init

You will be asked:

LLM provider (anthropic / openai) [anthropic]:
Anthropic API key:
Telegram bot token (from @BotFather):
Your Telegram user ID (from @userinfobot):
Additional user IDs (comma-separated, or Enter to skip):
Slack bot token (starts with xoxb-):
Slack report channel [#standup]:
Daily standup time (HH:MM, 24h) [09:00]:
Weekly review day (MON-SUN) [MON]:
Weekly review time (HH:MM, 24h) [08:00]:
Your name (for Compass memory):

All fields are validated. Press Enter to accept any default shown in brackets.

After init, verify your connections work:

compass test

What compass init creates:

~/.openclaw/
├── agent.json
├── hooks.json
├── channels.json
├── llm.json
└── compass/
    ├── boot.md
    ├── user.md
    ├── soul.md
    ├── identity.md
    ├── tools.md
    ├── version.json
    ├── skills/
    └── state/
        ├── tasks.md
        ├── decisions.md
        ├── blockers.md
        ├── commitments.md
        ├── metrics.md
        ├── daily-summaries/
        └── weekly-summaries/

Telegram pairing

After compass init, pair your bot:

1. Open Telegram
2. Search for your bot (the one you created with @BotFather)
3. Send: /start
4. Send: hi
5. Compass should respond

Running Compass

Foreground (for testing)

compass start       # runs in terminal, Ctrl+C to stop
compass stop        # stop from another terminal
compass status      # check if running

Background service (recommended for VMs)

compass service install     # installs systemd service and starts it
compass service status      # check service status
compass service stop        # stop service
compass service start       # start service
compass service uninstall   # remove service
compass logs                # view live logs

Commands

Core

compass init                       # First-time setup
compass start                      # Start agent (foreground)
compass stop                       # Stop running agent
compass status                     # Show running state and config
compass report --type daily        # Trigger daily standup now
compass report --type weekly       # Trigger weekly review now

Utilities

compass test                       # Test Telegram + Slack connections
compass logs                       # View agent logs
compass reset                      # Delete all state and config

Service (Linux)

compass service install            # Install + start systemd service
compass service start
compass service stop
compass service status
compass service uninstall

Maintenance

compass migrate                    # Run pending schema migrations
compass migrate --dry              # Preview migrations, no changes
compass rollback                   # Restore from last backup
compass doctor                     # Full health check
compass version                    # Show version and schema info

Using Compass in Telegram

Compass is silent by default. Mention it directly:

@Compass what's blocked?
@Compass who owns the landing page?
@Compass what did we decide about the API?
@Compass show this week's metrics
@Compass extract from this conversation

Slack reports

Compass posts automatically on your configured schedule:

• Daily standup — every day at your configured time
• Weekly review — every Monday (or your configured day)

Trigger manually:

compass report --type daily
compass report --type weekly

State files

All extracted information is stored as plain markdown in ~/.openclaw/compass/state/.

| File | What it stores | |---|---| | tasks.md | Active tasks with owner, status, deadline, priority | | decisions.md | Decision log with what, why, alternatives | | blockers.md | Open blockers with age tracking | | commitments.md | Commitments and deadlines | | metrics.md | Key metrics log |

Updating

npm install -g compass-ai@latest
compass migrate

Always run compass migrate after updating — it upgrades your state files safely (with automatic backup).

Troubleshooting

| Problem | Fix | |---|---| | compass: command not found | npm install -g compass-ai | | Telegram bot not responding | Send /start to your bot first, then hi | | Slack not posting | Run compass test to check the connection | | Token validation fails in init | Double-check the token format; re-run compass init | | Cron not firing | Run crontab -l to verify; check server timezone | | OpenClaw not found | npm install -g openclaw | | Schema outdated warning | Run compass migrate |

What Compass will not do (Phase 1)

• No sending emails
• No publishing content externally
• No spending money
• No modifying outside systems
• No autonomous decisions without your approval

License

MIT — see LICENSE