✨ Why Citio

Most teams can already chat with an LLM. The harder problem is letting a team ask for real engineering work from Slack without handing a raw shell and a pile of credentials directly to the model.

Citio closes that gap:

• 💬 Slack is the user interface: DM the bot or @mention it in a channel.
• 🧠 Claude Code or Codex is the execution engine: the provider CLI does the reasoning and planning.
• 🛡️ Citio is the control plane: it owns orchestration, session handling, repo setup, AWS/GitHub access, and a controlled MCP tool layer so the agent never touches raw credentials.
• 🏠 Everything runs in your infra: your container, your cloud account, your keys.

The result is something that can investigate bugs, inspect logs, edit code, and open pull requests, without a human sitting in the middle of every request.

Where it runs. Citio is a self-hosted container. This first version ships a native one-command AWS Fargate deploy (on Fargate Spot by default, ~$5–11/month, or citio pause to $0 when idle). Running on other hosts (a cheap VPS, Fly.io / Railway, or your own homelab) and a pay-per-use serverless mode are on the roadmap.

🆚 Citio vs. hosted Slack agents

Anthropic's Claude Tag (June 2026) popularized exactly this idea (@mention an AI teammate in Slack and it does the work in-thread), but it's an Anthropic-hosted service gated to Claude Team and Enterprise plans, Claude-only. Citio takes the self-hosted, bring-your-own-subscription path:

If you already pay for a Claude or ChatGPT subscription, Citio puts that same agent to work from Slack, no per-seat enterprise upgrade, no handing your code and credentials to someone else's cloud.

🧩 Features

• 🤝 Bring your own agent: Claude Code or OpenAI Codex, your subscription or API key.
• 🧰 Controlled MCP tools: investigate_codebase, read_file, write_file, create_branch, create_pr, run_command (allowlisted), check_ci_status, query_logs, recall_context, and more.
• 🔐 Credential boundary: the agent calls MCP tools; secrets live with Citio, not the model. Command execution is allowlisted and shell-metacharacter-rejected.
• 🧵 Slack-native: DMs and channel mentions, streamed progress, redacted output.
• 💾 Persistent workspace & memory: optional AWS EFS keeps repos, sessions, and provider auth across redeploys.
• 🪄 One-command installer: interactive setup wires up Slack, GitHub, provider auth, and deploys to ECS.

🏗️ How it works

Runtime shape:

1. A Slack request is normalized by the Slack adapter.
2. AgentRunner serializes work and manages provider sessions (one active task per container).
3. It spawns the Claude Code / Codex CLI as the agent, wired to Citio's MCP server via --mcp-config.
4. The agent uses MCP tools for codebase reads/writes, PR creation, log queries, and progress updates, never raw credentials.
5. Workspace, memory, and auth persist through EFS when enabled.

More detail: docs/ARCHITECTURE.md

🚀 Quickstart

Prerequisites

On your machine (the installer hard-checks for Docker, AWS CLI, and Git):

The agent CLIs (claude, codex), gh, and jq ship inside the container image: you don't install them on the host.

Accounts & tokens

• An agent subscription: Claude Max/Pro, or ChatGPT Go/Plus/Pro for Codex (API key works as a fallback).
• A Slack app (the installer can create it for you from a config token) + the target channel ID.
• A GitHub fine-grained PAT with contents: write + pull_requests: write on the repos you want worked on.

Setting up your AWS profile

Citio deploys into your own AWS account. This takes about 10 minutes from "no AWS CLI" to "ready to install". If aws sts get-caller-identity already prints your account ID, skip to Permissions.

1. Install the AWS CLI

Verify with aws --version (v2.x recommended).

2. Connect the CLI to your account

No AWS account yet? Create one at aws.amazon.com. Then pick one route:

Option A: IAM user + access key (simplest for a personal account)

1. AWS Console → IAM → Users → Create user (e.g. citio-admin)
2. Attach permissions (see Permissions below)
3. Open the user → Security credentials → Create access key → choose Command Line Interface (CLI)
4. Configure the profile:

aws configure --profile citio
# AWS Access Key ID:      AKIA...
# AWS Secret Access Key:  ...
# Default region name:    eu-west-2      # any region you like
# Default output format:  json

Option B: IAM Identity Center / SSO (if your org uses it)

aws configure sso                  # follow the browser prompts
aws sso login --profile citio

Verify either way: this must print your account ID:

aws sts get-caller-identity --profile citio

The installer lists your profiles automatically and re-runs this check before it touches anything.

Permissions

The deploy creates an ECR repository, an ECS cluster/service/task definition, an IAM task role, a security group, CloudWatch log groups, a Secrets Manager secret, and (optionally) an EFS filesystem.