Quickstart

Get Claudio running and execute your first productivity workflow in minutes. This guide covers installation, MCP configuration, and usage across all channels.

Prerequisites

Before you begin, ensure you have:

Python 3.10+ and Node.js 18+ installed
Claude Code CLI (for bot channels and automation scripts)
Cursor IDE (optional, for direct terminal usage)

This guide assumes you have a PropHero team account with access to ClickUp, Slack, and Google Workspace.

Installation

Clone the repository

git clone https://github.com/cuba1511/claudio.git
cd claudio

Set up Python environment

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

Configure environment variables

Copy the example environment file and fill in your values:

cp .env.example .env

Edit .env and set:

WORKSPACE_PATH=/path/to/claudio
CLAUDE_CLI_PATH=claude
ALLOWED_TOOLS=*
SKIP_PERMISSIONS=true
COMMAND_TIMEOUT=1800

See the Environment Configuration guide for detailed explanations of all variables.

Configure MCPs

Set up your MCP integrations in ~/.cursor/mcp.json (for Cursor) or ~/.claude.json (for CLI):

{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": ["-y", "@taazkareem/clickup-mcp-server@latest"],
      "env": {
        "CLICKUP_MCP_LICENSE_KEY": "your-license-key",
        "CLICKUP_API_KEY": "your-api-key",
        "CLICKUP_TEAM_ID": "your-team-id"
      }
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "slack-mcp-server@latest", "--transport", "stdio"],
      "env": {
        "SLACK_MCP_XOXC_TOKEN": "xoxc-your-token",
        "SLACK_MCP_XOXD_TOKEN": "xoxd-your-token"
      }
    }
  }
}

For complete MCP configuration instructions, see the MCP Setup guide.

Choose your channel

Claudio supports multiple interaction channels. Pick the one that fits your workflow:

Terminal (Cursor)
Telegram
Slack
Web Dashboard

Best for: Direct usage during development

Open Cursor IDE

Open the Claudio project directory in Cursor:

cursor .

Verify MCP configuration

Ensure your ~/.cursor/mcp.json is configured with the MCPs from the previous step.

Restart Cursor

Restart Cursor to load the MCP configuration.

Start chatting

Open the Claude chat panel in Cursor and start asking Claudio to help you:

Create a user story in ClickUp for adding dark mode to the settings page

Best for: Mobile access and quick commands on the go

Create a Telegram bot

Message @BotFather on Telegram and create a new bot with /newbot. Save your bot token.

Get your user ID

Message @userinfobot to get your Telegram user ID.

Configure the bot

Create channels/telegram/.env:

TELEGRAM_BOT_TOKEN=your-bot-token
ALLOWED_USER_IDS=your-user-id
WORKSPACE_PATH=/path/to/claudio
OPENAI_API_KEY=sk-your-openai-key  # For voice transcription

Install dependencies and start

cd channels/telegram
pip install -r requirements.txt
./start.sh

Message your bot

Find your bot on Telegram and send /start to begin chatting.

See the Telegram Channel guide for advanced configuration and commands.

Best for: Team collaboration and shared workflows

Create a Slack app

Go to api.slack.com/apps
Click Create New App → From scratch
Name it “Claudio” and select your workspace

Configure OAuth scopes

Under OAuth & Permissions, add these Bot Token Scopes:

chat:write
app_mentions:read
im:history
im:read
im:write

Enable Socket Mode

Under Socket Mode, enable it and generate an app-level token
Under Event Subscriptions, enable events and subscribe to:
- app_mention
- message.im

Install to workspace

Click Install to Workspace and authorize the app.

Configure the bot

Create channels/slack/.env:

SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_APP_TOKEN=xapp-your-app-token
SLACK_ALLOWED_USER_IDS=U1234567890
WORKSPACE_PATH=/path/to/claudio

Install dependencies and start

cd channels/slack
pip install -r requirements.txt
./start.sh

Message the bot

Send a DM to Claudio in Slack or mention @Claudio in any channel.

See the Slack Channel guide for slash commands and advanced usage.

Best for: Monitoring MCPs and interactive chat with streaming responses

Install dependencies

cd channels/web
pip install -r requirements.txt

Start the server

./start.sh
# Or for development with hot reload:
./start.sh --dev

Open the dashboard

Navigate to http://localhost:8000 in your browser.

Chat with Claudio

Click Chat in the navigation and start typing your requests.

The web dashboard provides real-time MCP health monitoring at http://localhost:8000/api/mcps/health.

Your first workflow

Let’s create a User Story in ClickUp using the ClickUp MCP integration:

Start a conversation

Using your preferred channel (Terminal, Telegram, Slack, or Web), ask Claudio:

Create a user story for adding a password reset feature to the login page

Claudio gathers context

Claudio will:

Read the parent Initiative or Epic for context
Use the User Story template from docs/integrations/clickup/templates/
Extract relevant information about the project

Task is created

Claudio will use the ClickUp MCP to create a task with:

Title and description
Acceptance criteria
Technical notes
Business value
Assignment to the Sprint Backlog list

Get the link

Claudio responds with a link to the newly created ClickUp task:

✅ Created User Story: "Add password reset feature"
📎 https://app.clickup.com/t/901213056238/TASK-123

💡 Next: Review the task and assign it to a sprint

This workflow uses multiple tools: get_workspace_hierarchy (context), get_task (parent info), and create_task (creation).

Next steps

Explore workflows

Discover pre-built workflows for product management, sprint reporting, and automation

Configure integrations

Set up ClickUp, GitHub, Slack, Google Docs, and other MCP integrations

Learn the architecture

Understand how Claudio’s channels, brain, and MCPs work together

Secure your setup

Configure rate limiting, user authorization, and permissions

Common commands

Here are some common requests you can make to Claudio across any channel:

Product management: “Create an initiative for improving onboarding flow”
Sprint planning: “Generate the sprint report for the current sprint”
Code tasks: “Create a GitHub issue for the bug we just discussed”
Communication: “Post a message in #engineering about today’s deployment”
Data analysis: “Analyze the conversion funnel from the last 7 days”
Meeting notes: “Find the meeting notes from yesterday’s standup”

Troubleshooting

MCP not found or connection error

Cause: The MCP server isn’t configured or credentials are invalid.Solution:

Verify your MCP configuration in ~/.cursor/mcp.json or ~/.claude.json
Check that all environment variables (API keys, tokens) are set correctly
Restart Cursor or the bot to reload the configuration
Test MCP health at http://localhost:8000/api/mcps/health (web dashboard)

Permission denied errors

Cause: SKIP_PERMISSIONS is not enabled or tool permissions are restricted.Solution: Set in your .env:

SKIP_PERMISSIONS=true
ALLOWED_TOOLS=*

Bot not responding

Cause: User not authorized, bot process crashed, or rate limit exceeded.Solution:

Check that your user ID is in ALLOWED_USER_IDS (Telegram) or SLACK_ALLOWED_USER_IDS (Slack)
Check bot logs in channels/{telegram|slack}/ or scripts/logs/
Verify the bot process is running: ps aux | grep bot.py
Restart the bot: ./channels/{channel}/start.sh

Command timeout

Cause: Task took longer than COMMAND_TIMEOUT (default 30 minutes).Solution: Increase the timeout in .env:

COMMAND_TIMEOUT=3600  # 1 hour

If you encounter authentication errors with MCPs (ClickUp, Slack, Google), double-check that your API keys and tokens are valid and have the required permissions.

Need help?

Architecture: Learn how Claudio works at Architecture
Channels: Detailed setup for Telegram, Slack, Web
Integrations: Configure ClickUp, GitHub, Slack, Google Docs
Configuration: Environment variables, Security, MCP setup

Get Started

Channels

Integrations

Workflows

Configuration

Prerequisites

Installation

Choose your channel

Your first workflow

Next steps

Explore workflows

Configure integrations

Learn the architecture

Secure your setup

Common commands

Troubleshooting

Need help?

Build docs developers (and LLMs) love

Get Started

Channels

Integrations

Workflows

Configuration

​Prerequisites

​Installation

​Choose your channel

​Your first workflow

​Next steps

Explore workflows

Configure integrations

Learn the architecture

Secure your setup

​Common commands

​Troubleshooting

​Need help?

Build docs developers (and LLMs) love

Prerequisites

Installation

Choose your channel

Your first workflow

Next steps

Common commands

Troubleshooting

Need help?