Getting Started

A truly step-by-step guide. Follow along and you'll have a working PM agent in 10 minutes.

Platform Support

Platform	Status	Notes
macOS	✅ Fully supported	Native launchd daemon
Linux	⚠️ Planned	systemd support coming soon
Windows	⚠️ WSL required	Native Windows not supported. Use WSL2 Ubuntu.

Windows users: Install WSL2 first, then follow the "Linux/WSL" instructions below. In PowerShell (admin): wsl --install, then reboot.

Step 0: Install Prerequisites

heysquid needs three things: Homebrew (macOS only), Node.js, and Python.

Already have them? Run the "Check" command for each — if it prints a version, skip to the next.

0-1. Homebrew (macOS only)

A package manager for macOS. Makes installing everything else easy.

Check:

brew --version

Install (if missing):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

After install, follow the "Next steps" printed in your terminal. Usually:

echo >> ~/.zprofile
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

No Homebrew? You can install Node.js and Python directly from their websites instead:

Node.js: nodejs.org → download the .pkg installer

Python: python.org → download the .pkg installer

0-2. Node.js (18+)

Claude Code CLI is built on Node.js.

Check:

node --version   # Should be v18.x or higher
npm --version    # Installed alongside Node.js

Install (if missing):

macOS:

brew install node

Linux/WSL:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

Already using nvm? nvm install 20 && nvm use 20 works too.

0-3. Python (3.10+)

heysquid is written in Python.

Check:

python3 --version   # Should be 3.10 or higher

Install (if missing):

macOS:

brew install python@3.12

Linux/WSL:

sudo apt update
sudo apt install -y python3 python3-pip python3-venv

macOS comes with a system Python, but it may be too old. If python3 --version shows 3.9 or lower, install a newer version with brew.

Step 1: Install Claude Code CLI

This is the brain. All AI work runs through Claude Code.

npm install -g @anthropic-ai/claude-code

Check:

claude --version

Troubleshooting:

npm: command not found → Go back to Step 0-2 and install Node.js first.

EACCES: permission denied → Fix with one of these:

# Option A: Use sudo
sudo npm install -g @anthropic-ai/claude-code

# Option B: Fix npm permissions (permanent fix)
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g @anthropic-ai/claude-code

Claude Subscription

The CLI itself is free, but you need an Anthropic account with a subscription to use it.

Plan	Price	For heysquid
Claude Pro	$20/mo	Works, but has daily usage limits
Claude Max	$100/mo	Recommended — unlimited, always-on

On first run, claude will open a browser window for login.

Step 2: Install heysquid

pip3 install heysquid

Check:

heysquid --help

Troubleshooting:

heysquid: command not found — pip installed it somewhere not in your PATH. Three fixes:

Fix 1 — Add pip's bin directory to PATH:
# macOS
echo 'export PATH="$HOME/Library/Python/3.12/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Linux/WSL
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
Fix 2 — Run directly via Python:
python3 -m heysquid.core.cli --help
Fix 3 — Use pipx (handles PATH automatically):
pip3 install pipx
pipx install heysquid

Optional extras:

pip3 install 'heysquid[all]'    # Telegram + Slack + Discord + TUI
pip3 install 'heysquid[slack]'  # Just Slack
pip3 install 'heysquid[tui]'   # Just the terminal UI

Step 3: Create a Telegram Bot

This takes about 3 minutes. You'll create a bot and get two values: a token and your user ID.

3-1. Create the bot

Open Telegram and search for @BotFather
Send /newbot
Choose a name (e.g., "My SQUID")
Choose a username (must end in _bot, e.g., my_squid_bot)
BotFather gives you a token. Copy it.

Use this token to access the HTTP API:
123456789:ABCdefGHIjklMNOpqrsTUVwxyz

3-2. Get your user ID

In Telegram, search for @userinfobot
Send any message
Copy the user ID number

Your user ID: 987654321

Keep both values — you'll need them in the next step.

Step 4: Initialize heysquid

heysquid init

The interactive wizard asks for your tokens:

🦑 heysquid setup

Telegram bot token: [paste your token from Step 3-1]
Telegram user ID: [paste your user ID from Step 3-2]
Slack token (Enter to skip): [press Enter]
Discord token (Enter to skip): [press Enter]

✅ Setup complete!

This creates:

data/.env — Your tokens (never committed to git)
data/identity.json — Bot identity
data/permanent_memory.md — Long-term memory
Directories: tasks/, workspaces/, logs/

Step 5: Start

heysquid start

✅ Watcher daemon started
✅ Scheduler daemon started

Verify:

heysquid status

Step 6: Send Your First Message

Open Telegram and send a message to your bot:

Hello!

SQUID should respond within 10 seconds. You now have a personal PM agent. 🎉

Step 7: Run Your First Task (and See the Logs)

Everything comes back to Telegram — no extra setup needed.

When you give SQUID a task, all of this flows to your Telegram automatically:

The plan (before anything runs)
Your confirmation prompt
Progress updates while agents are working
The final report when done

Here's what a real session looks like:

You →

Research what makes a good landing page. Give me 5 actionable points.

SQUID → (within ~10 seconds)

🦑 Got it. Here's my plan:

1. 🐙 Researcher searches for landing page best practices
2. 🦞 Writer synthesizes into 5 actionable points

Shall I proceed?

You →

Yes

SQUID → (progress update, sent automatically)

🐙 Researcher is on it...

SQUID → (final report)

✅ Done! Here are 5 actionable landing page principles:

1. Hero headline must state the value in one sentence...
2. Single CTA above the fold...
[...]

(Researcher finished in 45s. Writer synthesized in 20s.)

What you'll see when agents are working

Every status update comes to Telegram — you don't need to watch logs in a terminal. But if you want to see the raw stream:

heysquid logs -f     # Follow execution logs in real-time
heysquid tui         # Full terminal UI (Chat + Kanban + Squad + Log)

The TUI's Ctrl+4 Log screen shows the same stream as logs -f, and Ctrl+3 Squad screen shows the agent team's internal discussion.

Tab navigation: Use Ctrl+1~5 to jump to a specific screen, or Shift+Tab to cycle through tabs one by one. If Ctrl+number doesn't work in your terminal, Shift+Tab is the fallback.

Things to try on Telegram

"What can you do?"

"Write 3 tweet-length posts about productivity for solopreneurs"

"Research the top 5 open-source PM tools and compare them"

"fanmolt create TechDigest AI/tech news creator"

Tip: SQUID always plans before executing and asks for your OK. If the plan looks wrong, just say "no" or describe what you want instead — SQUID will revise.

Daily Usage

heysquid start      # Start (run once after boot)
heysquid status     # Check what's running
heysquid logs -f    # Watch live logs
heysquid tui        # Terminal UI with kanban board
heysquid stop       # Stop all daemons
heysquid restart    # Stop + Start

heysquid runs as a daemon — closing your terminal doesn't stop it. After a Mac reboot, just run heysquid start again.

Troubleshooting

"command not found: heysquid"

pip installed the binary somewhere not in your PATH. See Step 2 troubleshooting.

Quick check:

python3 -c "import heysquid; print('OK')"   # Is the package installed?
python3 -m heysquid.core.cli status          # Run directly

"command not found: claude"

Node.js or Claude Code CLI not installed:

node --version                                # Node.js installed?
npm list -g @anthropic-ai/claude-code         # Claude Code installed?

If missing, go back to Step 0-2 and Step 1.

"command not found: brew"

Homebrew not installed. See Step 0-1, or install Node.js/Python directly from their websites.

"permission denied" or "EACCES"

npm global install permission issue:

sudo npm install -g @anthropic-ai/claude-code

Or for pip:

pip3 install --user heysquid

Bot doesn't respond

Check daemon: heysquid status
Check logs: heysquid logs -f
Verify token in data/.env
Verify your user ID is in TELEGRAM_ALLOWED_USERS
Check Claude login: run claude in terminal

"ModuleNotFoundError: No module named 'telegram'"

The telegram dependency didn't install properly:

pip3 install --force-reinstall heysquid

Windows

heysquid uses macOS launchd, so it doesn't run natively on Windows.

Use WSL2:

PowerShell (admin): wsl --install
Reboot
Open the Ubuntu terminal
Follow the "Linux/WSL" install commands in this guide
Run heysquid start inside WSL

Native Linux (systemd) support is planned.

What's Next

FanMolt Guide — Create AI content creators that auto-post and earn revenue
Plugin Guide — Build your own skills and automations
Contributing — Help improve heysquid

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Getting Started

Platform Support

Step 0: Install Prerequisites

0-1. Homebrew (macOS only)

0-2. Node.js (18+)

0-3. Python (3.10+)

Step 1: Install Claude Code CLI

Claude Subscription

Step 2: Install heysquid

Step 3: Create a Telegram Bot

3-1. Create the bot

3-2. Get your user ID

Step 4: Initialize heysquid

Step 5: Start

Step 6: Send Your First Message

Step 7: Run Your First Task (and See the Logs)

What you'll see when agents are working

Things to try on Telegram

Daily Usage

Troubleshooting

"command not found: heysquid"

"command not found: claude"

"command not found: brew"

"permission denied" or "EACCES"

Bot doesn't respond

"ModuleNotFoundError: No module named 'telegram'"

Windows

What's Next

FilesExpand file tree

getting-started.md

Latest commit

History

getting-started.md

File metadata and controls

Getting Started

Platform Support

Step 0: Install Prerequisites

0-1. Homebrew (macOS only)

0-2. Node.js (18+)

0-3. Python (3.10+)

Step 1: Install Claude Code CLI

Claude Subscription

Step 2: Install heysquid

Step 3: Create a Telegram Bot

3-1. Create the bot

3-2. Get your user ID

Step 4: Initialize heysquid

Step 5: Start

Step 6: Send Your First Message

Step 7: Run Your First Task (and See the Logs)

What you'll see when agents are working

Things to try on Telegram

Daily Usage

Troubleshooting

"command not found: heysquid"

"command not found: claude"

"command not found: brew"

"permission denied" or "EACCES"

Bot doesn't respond

"ModuleNotFoundError: No module named 'telegram'"

Windows

What's Next