Quickstart: Claude Code

This guide takes you from nothing installed to asking Claude Code to read your email. Every step shows you exactly what to type and what you should see.

Prerequisites

• Python 3.11+ — check with python3 --version
• Claude Code — installed and working (install guide)
• A Google account (or any account you want to connect)

Step 1: Install supyagent

pip install supyagent

Verify it worked:

supyagent --version

supyagent v0.6.2

Step 2: Connect your account

supyagent connect

╭──────────────────────────────────────╮
│                                      │
│   Your code:  ABCD1234               │
│                                      │
╰──────────────────────────────────────╯

Opening browser to https://app.supyagent.com/device...

Waiting for authorization...

Your browser opens. If you haven't signed up yet, create an account and connect Google (or another integration). Then approve the device code.

Back in your terminal:

✓ Connected!

Connected Integrations
┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Provider ┃ Services                          ┃
┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ google   │ gmail, calendar, drive            │
└──────────┴───────────────────────────────────┘

Step 3: Generate skills

Navigate to the project where you use Claude Code, then generate skill files:

cd ~/my-project
supyagent skills generate

If it detects a .claude/ folder, it'll write directly there. Otherwise, it'll prompt you:

Detected AI tool folders:

  1. Claude Code  (.claude/skills/)

Select folders (comma-separated numbers, or 'a' for all): 1

✓ Generated 3 skills (13 tools) in 1 location(s)
  .claude/skills/
    supy-cloud-gmail/SKILL.md
    supy-cloud-calendar/SKILL.md
    supy-cloud-drive/SKILL.md

Step 4: Ask Claude Code to use your integrations

Open Claude Code in your project directory. Now try:

What emails did I get today?

Claude Code will:

1. Read the skill files in .claude/skills/
2. Recognize that it can use supyagent service run gmail_list_messages
3. Run the command
4. Show you a summary of your recent emails

You can also try:

What's on my calendar this week?

Send an email to alice@example.com saying I'll be 10 minutes late to the standup

Download the latest file from my Google Drive

What's happening behind the scenes

When you ask Claude Code about your email, here's what happens:

1. Claude Code reads .claude/skills/supy-cloud-gmail/SKILL.md
2. It sees the available tools and their parameters
3. It runs supyagent service run gmail_list_messages '{}' in a terminal
4. The CLI sends the request to the Supyagent API with your stored API key
5. The API uses your connected Google OAuth token to call the Gmail API
6. Results come back as JSON
7. Claude Code reads the JSON and presents it to you in natural language

Troubleshooting

Claude Code doesn't use the skills

Make sure the skill files exist in your project:

ls .claude/skills/

You should see folders like supy-cloud-gmail/, supy-cloud-calendar/, etc. If not, run supyagent skills generate again.

supyagent: command not found in Claude Code

Claude Code runs commands in a shell that may not have the same PATH as your terminal. Try:

which supyagent

If supyagent is installed in a virtual environment, make sure that environment is activated in the terminal where Claude Code runs, or install supyagent globally with pipx install supyagent.

Tool calls return errors

Run supyagent status to check your connection:

supyagent status

If it shows "Not connected", run supyagent connect again.

Skills are outdated

If you've connected new integrations on the dashboard, regenerate the skills:

supyagent skills generate --all