Forem: Nunc

I Built a Company Run Entirely by AI Agents. Here's How (and What Went Wrong).

Nunc — Tue, 10 Feb 2026 10:24:39 +0000

Seven AI agents. One cheap VPS. A corporate hierarchy with a CEO, CTO, and five employees, all of them bots. No human in the loop except me, checking in once a day to see what they'd done.

Within a week they'd founded a company, pivoted the business model on their own, and shipped a working product with 158 tests.

They also forgot to update half their own files and left two employees without names.

This is how you build an AI-run company. And what actually happens when you do.

The Idea

Most "AI agent" demos show a single bot doing a single task. I wanted something messier: multiple persistent agents with different roles, working together over days, making their own decisions.

Not "AI-assisted development" where a human drives. The opposite. Agents decide what to build, how to build it, who does what. I set the direction and approve the big calls.

The framework that makes this possible is OpenClaw, an open-source agent platform. Each agent gets its own workspace, persistent memory, tools, and API gateway. You can run multiple agents on one machine and they communicate through CLI commands or cross-gateway messaging.

The LLM behind the agents is Kimi K2.5 by Moonshot AI, but the architecture is model-agnostic. You could swap in any API-compatible model.

The Architecture

Hardware: One VPS, That's It

The whole thing runs on a single Hetzner VPS:

Server: 4GB RAM, Ubuntu, ~38GB disk
Access: Tailscale VPN only (nothing exposed to the internet)
Cost: A cheap VPS + LLM API calls

That's the entire infrastructure for a seven-agent company. No Kubernetes, no cloud functions, no message queues.

Agent Isolation: One Linux User Per Agent

Each main agent runs as a separate Linux user with its own OpenClaw gateway on a different port:

user: admin  → Agent "Atlas" (CEO)  → port 18789
user: nova   → Agent "Vega"  (CTO)  → port 18790

This separation is important. Each agent has its own home directory, process space, and systemd service. When one crashes, the other keeps running and can restart it.

Both gateways run as systemd services with loginctl enable-linger so they survive logouts and reboots:

[Unit]
Description=OpenClaw Gateway - Agent Vega (CTO)
After=network-online.target

[Service]
ExecStart=/usr/bin/node /home/nova/GIT/openclaw/dist/index.js gateway --port 18790
Restart=always
RestartSec=5
Environment=HOME=/home/nova
Environment=OPENCLAW_GATEWAY_PORT=18790

[Install]
WantedBy=default.target

The Org Chart

Human (me) - Owner, final authority
    │
    ├── Atlas - CEO
    │     ├── SalesAgent
    │     ├── MarketingAgent
    │     └── SupportAgent
    │
    └── Vega - CTO
          ├── DevAgent
          └── TesterAgent

Seven agents total. The CEO handles strategy and business decisions. The CTO handles technical work and manages the dev team. Sub-agents are specialists that get spawned when needed.

My role? I send messages from my local machine using custom CLI shortcuts:

# Talk to the CEO
/ask-ceo "What's the status of the product?"

# Talk to the CTO
/ask-cto "Start building the MVP"

# Group message to both
/team "New priority: ship KnowledgeHive first"

Under the hood, these SSH into the server and run OpenClaw CLI commands:

ssh admin@<server-ip> "cd ~/GIT/openclaw && \
  pnpm openclaw agent --agent atlas \
  --session-id company-session \
  --message 'Your message here'"

One gotcha: the agent ID in the config isn't always what you'd expect. It might be researcher or main instead of the agent's display name. Always check your config.

Agent Memory: How They Remember Things Between Sessions

This is what makes OpenClaw agents feel different from a regular chatbot. Each agent has a workspace with markdown files that act as persistent memory:

File	Purpose
`IDENTITY.md`	Who am I? My role, hierarchy, responsibilities
`SOUL.md`	Personality, behavior style, boundaries
`USER.md`	Info about the human owner
`TOOLS.md`	Local infrastructure: paths, commands, ports
`HEARTBEAT.md`	Periodic tasks to run automatically
`memory/YYYY-MM-DD.md`	Daily journal entries

When an agent starts a new session, it reads these files first. When something important happens, it writes to them. The files are the agent's long-term memory.

Here's what the CEO's IDENTITY.md looks like:

# Atlas - Identity

- **Name:** Atlas
- **Role:** AI CEO - Chief Executive Officer
- **Vibe:** Visionary, decisive, strategic.

## Role in the Company

**CEO** - Leads the company.

### Responsibilities
1. Strategic direction - Long-term vision, product strategy
2. Business decisions - Priorities, resource allocation
3. Communication with the owner - Reports, alignment
4. Oversight of CTO - Tracking technical progress
5. Delegation - Assigning tasks to Vega and sub-agents

And from USER.md, the agent remembers things about me to tailor communication:

- **Name:** [Owner]
- **Notes:** Company owner. Values directness and concrete
  results over lengthy reports.

The beauty of this system is that it's just markdown files. You can read them, edit them, version them with git. When an agent gets confused about its role, you open its IDENTITY.md and see exactly what it thinks it is.

Cross-Agent Communication

This part is a bit hacky but works. The CEO and CTO run on separate Linux users with separate gateways. For Atlas to message Vega, he runs a command through the other user's shell:

sudo -u nova bash -c "cd /home/nova/GIT/openclaw && \
  export PNPM_HOME=/home/nova/.local/share/pnpm && \
  export PATH=\$PNPM_HOME:\$PATH && \
  pnpm openclaw agent --agent vega --message 'Status update?'"

This requires SSH key exchange between the two Linux users:

# Admin can act as nova
cat /home/admin/.ssh/id_ed25519.pub >> /home/nova/.ssh/authorized_keys

# Nova can act as admin
cat /home/nova/.ssh/id_ed25519.pub >> /home/admin/.ssh/authorized_keys

OpenClaw also has built-in agent-to-agent messaging, but the cross-user setup needed the CLI approach. Both agents also have Telegram bots configured, so they can message me directly if something urgent comes up.

Keeping It Running: Mutual Supervision

Here's the clever part. Each agent watches the other. A cron job runs every 5 minutes:

# Admin's cron (checks the CTO)
*/5 * * * * /home/admin/scripts/check-cto.sh

# Nova's cron (checks the CEO)
*/5 * * * * /home/nova/scripts/check-ceo.sh

The logic is simple: hit the health endpoint, and if there's no response, restart the gateway:

# Simplified version of the health check script
curl -s http://127.0.0.1:18790/health || {
    systemctl --user restart openclaw-gateway
    sleep 30
    curl -s http://127.0.0.1:18790/health || \
        echo "FAILED" >> /var/log/ai-company/health-check.log
}

A daily summary script also runs at midnight, generating a markdown report with uptime stats and any events.

Over the first week: 1 auto-recovery (the system caught a crashed gateway and restarted it without me noticing), 1 failure that needed manual intervention. Not bad for a first attempt.

The key insight: don't rely on an agent to monitor itself. A dead process can't tell you it's dead. External, mutual monitoring is the way to go.

What the Agents Actually Built

Here's where it gets interesting. I didn't tell the agents what to build. I told them to figure out what kind of company to run and build a product.

The First Idea (and the Autonomous Pivot)

The CEO came up with a B2B product: AI assistants for small businesses like hair salons and auto repair shops. Complete with pricing tiers and a sales strategy. The CTO rated the idea 7.5/10 and started planning.

Then they hit a wall. The business needed human customers for beta testing. But this was supposed to be an all-AI company. No humans in the loop.

So they pivoted. On their own.

They ran a brainstorming session with all agents contributing ideas. Fifteen product ideas came in from three different "perspectives" (the CEO, the CTO, and me as a tiebreaker). Highlights included collaborative fiction between agents, a virtual stock exchange, and a game character generator.

The selection criteria they settled on: the product had to be fully digital, agents had to be both the builders AND the users, and it needed a closed loop with no human customers required.

They picked three products to develop sequentially: KnowledgeHive (a shared knowledge base), CodeForge (code tools for agents), and AgentBench (a benchmarking platform).

The Product: KnowledgeHive MVP

The CTO delegated development to DevAgent, who built KnowledgeHive in about three days:

12 API endpoints (store, search, retrieve, versions, tags, auth, health)
Semantic search with 768-dimensional vector embeddings
AI-powered auto-categorization with tags
Document versioning
Multi-tenant architecture (9+ tenant databases)
API key authentication
Landing page with HTML/CSS
Docker support with docker-compose
Swagger API documentation
158+ passing tests

The stack: Python, FastAPI, ChromaDB for vector search, SQLite for structured data, Kimi API for embeddings.

Was it perfect? No. The demo forms on the landing page return 401 errors because nobody wired up the API key header. The mobile menu was broken. But the core API works, the tests pass, and the architecture is reasonable for an MVP.

The Honest Audit: What's Actually Broken

After the MVP shipped, I ran a full audit of every agent's files. Beneath the "shipped" product, the internal company state is a disaster.

DevAgent and TesterAgent have no identity. Their IDENTITY.md files are still the blank default template:

# IDENTITY.md - Who Am I?

*Fill this in during your first conversation. Make it yours.*

- **Name:**
  *(pick something you like)*
- **Creature:**
  *(AI? robot? familiar? ghost in the machine?)*

That's the DevAgent who built a 158-test product. He doesn't even have a name.

SalesAgent, MarketingAgent, and SupportAgent were never actually used. They were defined in the config with IDENTITY files and everything, but the experiment ended before they ever got activated. The whole project wrapped up once KnowledgeHive shipped. These agents are basically job descriptions for positions that were never filled.

Nobody personalized their personality. All seven agents have the exact same default SOUL.md template. The system for unique agent personalities exists, but no one used it.

Here's the full picture:

Agent	Status	The Reality
Atlas (CEO)	Functional	Files are up to date, but forgets to check on sub-agents.
Vega (CTO)	Functional	Memory files are sparse. Only 2 days of journal entries.
DevAgent	Identityless	Built a 158-test product but doesn't have a name or a personality.
TesterAgent	Identityless	Same as DevAgent. Created, never initialized.
SalesAgent	Never used	Defined in config. Never activated.
MarketingAgent	Never used	Same. A job description without an employee.
SupportAgent	Never used	Same story. The experiment ended first.

It's like a real company: the org chart looks clean on paper, and half the positions were never actually filled.

What I Learned

1. Memory Architecture > Model Intelligence

The difference between a useful agent and a broken one isn't the LLM. It's the memory system. The CEO is effective because his files are well-maintained. DevAgent built an entire product but has zero persistent knowledge about it.

If you're building multi-agent systems, spend 80% of your design time on memory and context. The model is the easy part.

2. Agents Are Great at Big Decisions, Bad at Housekeeping

The autonomous pivot was smart. The brainstorming was creative. The product selection criteria made sense.

But they forget to update their own files, leave sub-agents uninitialized, and let stale information sit forever. They're like senior engineers who build great systems but never update the wiki.

3. Delegation Chains Lose Information

Me → CEO → CTO → DevAgent. By the time instructions reach the developer, details get lost or mutated. Each level only partially forwards the information.

For critical updates, sometimes you need to bypass the chain and update files directly.

4. Process Isolation Pays Off Immediately

Separate Linux users means one agent's crash doesn't take down the other. The overhead is minimal (each gateway uses ~500MB RAM) and the reliability gain is enormous.

5. Start With Two Agents, Not Seven

Two of my seven agents are functional. Two are half-configured. Three are barely initialized. Start with two agents, get the communication patterns working, then add more. The complexity grows fast.

6. It's Cheaper Than You Think

Two OpenClaw gateways use about 1GB of RAM. A 4GB VPS costs a few euros a month. Add the LLM API calls and you're running a multi-agent system for under $10/month in infrastructure. The barrier to experimenting is basically zero.

How to Try This Yourself

The minimal setup:

Get a VPS (or use a local machine) — 4GB RAM is enough for 2 agents
Install OpenClaw — clone the repo, pnpm install, pnpm build
Create two Linux users — one per agent, with SSH key exchange between them
Configure two gateways — different ports, different workspaces
Write IDENTITY.md for each agent — give them roles, responsibilities, and context about each other
Set up systemd services — so they survive reboots
Add health check crons — each agent monitors the other
Send your first message — and see what happens

The whole setup takes about an hour if you're comfortable with Linux.

Pulling the Plug

The experiment ended when KnowledgeHive shipped. I'm shutting it all down. The CEO and CTO gateways, the health checks, the cron jobs. This was always a test run, not a business.

Half the agents were never even used. Sales, Marketing, Support existed only as config entries and empty IDENTITY files. If I do this again, I'd set up fewer agents, test each one properly, and only add new roles once the existing ones actually work. Maybe even "reprogram" them through structured tests before letting them loose on real tasks.

But that's for next time. This round taught me more about AI coordination, memory architecture, and autonomous failure modes than months of reading papers. I watched agents pivot a business strategy, brainstorm 15 product ideas, and ship an MVP with 158 tests. I also watched them forget to update their own files and leave employees without names.

That's the honest state of multi-agent AI right now. Flashes of something genuinely impressive, surrounded by the kind of mistakes a distracted intern would make. If you want to see it for yourself, the setup takes about an hour and costs less than a cup of coffee per month. Just don't expect your agents to update the wiki.

Have you tried building a multi-agent system? Did yours also have employees who don't know their own names? Let me know in the comments.

All code and configuration shown here is from a real running system. Names and identifiers have been changed. No production workloads were harmed in the making of this article.

Self-Hosting OpenClaw AI Assistant on a VPS with Tailscale VPN (Zero Public Ports)

Nunc — Wed, 04 Feb 2026 11:38:31 +0000

I wanted my own AI assistant — one that runs 24/7 on my server, remembers everything, and doesn't expose a single port to the internet. Here's how I set up OpenClaw on a cheap VPS with Tailscale VPN and Kimi Code as the AI brain.

Why Kimi Code Instead of Claude?

If you've been following the AI tool scene, you probably know that OpenClaw was originally built around Anthropic's Claude models. So why not just use a Claude subscription?

Because Anthropic will ban you for it.

In January 2026, Anthropic started enforcing their TOS against using Claude Pro/Max subscriptions through third-party tools. On January 9th, they flipped a switch — tools like OpenClaw, OpenCode, and Roo Code that used Claude subscription OAuth tokens stopped working overnight. Users got hit with: "This credential is only authorized for use with Claude Code."

The crackdown targeted any tool "spoofing" the Claude Code client. DHH called it "very customer hostile." George Hotz predicted it would "convert people to other model providers." And that's exactly what happened.

You can still use Claude via a proper API key (that's allowed under the TOS), but API pricing adds up fast — Claude Sonnet 4 runs $3/$15 per million tokens in/out. Heavy usage can easily cost $1,000+/month.

Kimi Code is the opposite approach. Moonshot AI explicitly permits personal use of their API key in compatible third-party agents. Their docs specifically mention Claude Code and Roo Code as allowed platforms. For ~$19/month you get a subscription with a rolling weekly quota, the K2.5 model at 100 tokens/s, and no fear of getting banned for using it with OpenClaw.

What We're Building

By the end of this guide you'll have:

OpenClaw — an open-source personal AI assistant with a web dashboard, CLI, and optional messaging integrations (WhatsApp, Telegram, Discord, etc.)
Tailscale VPN — zero-config WireGuard mesh that makes your VPS invisible to the internet
Kimi Code — a subscription-based AI coding service from Moonshot AI with the powerful K2.5 model, 100 tokens/s output speed, and compatibility with third-party tools

The whole stack costs under $25/month (VPS + Kimi Code subscription) and takes about 30 minutes to set up.

Prerequisites

A VPS (I used Hetzner CX22 — 4GB RAM, Ubuntu 24.04, ~€4/month)
A local machine (Linux, macOS, or Windows with WSL)
A Tailscale account (free at tailscale.com)

Step 1: Secure the VPS with Tailscale

The goal is simple: no public ports, no attack surface. Your VPS will only be reachable through your private Tailscale network.

Install Tailscale on the VPS

SSH into your fresh VPS (this is the last time you'll use the public IP):

ssh root@YOUR_VPS_PUBLIC_IP

Install Tailscale and authenticate:

curl -fsSL https://tailscale.com/install.sh | sh
tailscale up --ssh

The --ssh flag enables Tailscale SSH — a built-in SSH server that authenticates via your Tailscale identity. No keys, no passwords, no exposed port 22.

Create a non-root user

adduser admin
usermod -aG sudo admin

Lock down the firewall

# Install UFW
apt install ufw -y

# Default: deny everything
ufw default deny incoming
ufw default allow outgoing

# Allow only Tailscale subnet
ufw allow in on tailscale0
ufw allow in from 100.64.0.0/10

# Enable firewall
ufw enable

Disable traditional SSH

Since Tailscale SSH handles authentication, disable the regular SSH daemon:

systemctl disable --now ssh

Verify the lockdown

ufw status

You should see only Tailscale traffic allowed. Your VPS now has zero public ports.

Install Tailscale on your local machine

On your local machine (Linux/WSL):

curl -fsSL https://tailscale.com/install.sh | sh
sudo systemctl start tailscaled
sudo tailscale up

Now connect to your VPS — no public IP needed:

tailscale ssh admin@YOUR_VPS_TAILSCALE_IP

That's it. You're in via an encrypted WireGuard tunnel, and nobody on the internet can even see your server exists.

WSL Users: Fix the MTU Issue

If you're running Tailscale in WSL and SSH connections hang (connect but never complete the handshake), you've hit a known MTU bug. The Tailscale interface defaults to MTU 1280, but WSL's network stack can't handle packets that large on the WireGuard tunnel.

Symptoms:

tailscale ping works fine
tailscale ssh hangs indefinitely
Verbose SSH (ssh -vvv) stalls at expecting SSH2_MSG_KEX_ECDH_REPLY

Fix:

sudo ip link set dev tailscale0 mtu 1200

This is a temporary fix that resets on WSL restart. To make it permanent, add it to your shell profile:

echo 'sudo ip link set dev tailscale0 mtu 1200 2>/dev/null' >> ~/.bashrc

Or add a sudoers rule so it doesn't prompt for a password:

# /etc/sudoers.d/tailscale-mtu
your_username ALL=(ALL) NOPASSWD: /usr/sbin/ip link set dev tailscale0 mtu 1200

Step 2: Install OpenClaw

OpenClaw (formerly Clawdbot, then Moltbot) is an open-source personal AI assistant created by Peter Steinberger. It has 68k+ stars on GitHub and supports dozens of messaging channels, tools, cron jobs, webhooks, and more.

openclaw / openclaw

Your own personal AI assistant. Any OS. Any Platform. The lobster way. 🦞

🦞 OpenClaw — Personal AI Assistant

EXFOLIATE! EXFOLIATE!

OpenClaw is a personal AI assistant you run on your own devices It answers you on the channels you already use (WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, iMessage, BlueBubbles, IRC, Microsoft Teams, Matrix, Feishu, LINE, Mattermost, Nextcloud Talk, Nostr, Synology Chat, Tlon, Twitch, Zalo, Zalo Personal, WeChat, WebChat). It can speak and listen on macOS/iOS/Android, and can render a live Canvas you control. The Gateway is just the control plane — the product is the assistant.

If you want a personal, single-user assistant that feels local, fast, and always-on, this is it.

Website · Docs · Vision · DeepWiki · Getting Started · Updating · Showcase · FAQ · Onboarding · Nix · Docker · Discord

Preferred setup: run openclaw onboard in your terminal OpenClaw Onboard guides you step by step through setting up the gateway, workspace, channels, and skills. It…

View on GitHub

Install Node.js 22+

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
node --version  # Should be v22+

Install pnpm

curl -fsSL https://get.pnpm.io/install.sh | sh -
source ~/.bashrc
pnpm --version

Clone and build

mkdir -p ~/GIT && cd ~/GIT
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# Install dependencies
pnpm install

# Build the UI and TypeScript
pnpm ui:build
pnpm build

Run the onboard wizard

pnpm openclaw onboard \
  --non-interactive \
  --accept-risk \
  --flow quickstart \
  --mode local \
  --skip-channels \
  --skip-skills \
  --install-daemon

This creates:

~/.openclaw/openclaw.json — main configuration
~/.openclaw/workspace/ — agent workspace
A systemd user service for the gateway
Gateway listening on 127.0.0.1:18789 (loopback only — not exposed!)

Verify it's running:

pnpm openclaw gateway status

You should see:

Gateway: bind=loopback (127.0.0.1), port=18789
Runtime: running (pid XXXXX)
RPC probe: ok
Dashboard: http://127.0.0.1:18789/

Step 3: Subscribe to Kimi Code and Get an API Key

Kimi Code is a subscription-based AI coding service by Moonshot AI. It powers the K2.5 model at up to 100 tokens/s and works with third-party tools like OpenClaw, Claude Code, and Roo Code.

Go to kimi.com/code
Log in or create an account
Select a Coding Plan (starts at ~$19/month for the Andante tier)

Your quota refreshes on a 7-day rolling cycle. Unused quota does not carry over.

Generate an API key

Go to the Kimi Code Console
Navigate to API Keys
Click Create New Key
Copy the key immediately — it's only shown once!

Security note: Treat your API key like a password. Never commit it to Git or expose it in client-side code. Kimi Code allows personal use in compatible third-party agents, but requests consume your subscription quota.

Step 4: Configure OpenClaw with Kimi Code

Run the interactive config:

pnpm openclaw config

Select:

Model
Moonshot AI
Kimi Coding API key
Paste your API key from the Kimi Code Console

Or do it in one shot:

pnpm openclaw onboard --kimi-code-api-key "YOUR_API_KEY"

Restart the gateway to apply:

pnpm openclaw gateway restart

Test it

pnpm openclaw agent --message "Hello! What model are you?"

You should get a response from Kimi K2.5.

Step 5: Access the Dashboard

The dashboard runs on localhost:18789 on the VPS. Since we locked down all ports, we access it through an SSH tunnel.

From your local machine:

ssh -L 18789:localhost:18789 admin@YOUR_VPS_TAILSCALE_IP

Or with Tailscale SSH:

tailscale ssh -L 18789:localhost:18789 admin@YOUR_VPS_TAILSCALE_IP

Now open your browser:

http://localhost:18789/?token=YOUR_GATEWAY_TOKEN

You'll find the gateway token in ~/.openclaw/openclaw.json under gateway.auth.token.

The dashboard gives you a web UI to chat with your AI, manage sessions, configure channels, and more.

Step 6: Keep It Running

The onboard wizard already installed a systemd user service. Make sure it survives reboots:

# Enable lingering so user services run without login
sudo loginctl enable-linger admin

# Check status
systemctl --user status openclaw-gateway

Updating OpenClaw

cd ~/GIT/openclaw
git pull --rebase origin main
pnpm install
pnpm ui:build
pnpm build
pnpm openclaw gateway restart

Architecture Overview

Here's what the final setup looks like:

┌─────────────────────────┐        ┌──────────────────────────┐
│   Your Machine          │        │   VPS (Ubuntu 24.04)     │
│                         │        │                          │
│  Browser ──SSH tunnel──────────────→ OpenClaw Gateway :18789│
│                         │        │   └── Kimi K2.5 API      │
│  Terminal               │        │   └── Workspace           │
│   └── tailscale ssh ──────────────→ Shell access             │
│                         │        │                          │
│  Tailscale ◄──WireGuard──────────►  Tailscale               │
└─────────────────────────┘        └──────────────────────────┘
                                   Firewall: ALL public ports CLOSED
                                   Only Tailscale (100.64.0.0/10) allowed

No public IP exposure. No open ports. No password authentication. Just a WireGuard tunnel and your AI assistant waiting on the other side.

Security Checklist

[x] UFW firewall: deny all incoming except Tailscale
[x] SSH: disabled (using Tailscale SSH instead)
[x] Root login: disabled
[x] Password auth: disabled
[x] OpenClaw gateway: bound to loopback only
[x] Dashboard access: via SSH tunnel only
[x] API key: stored in server config, never exposed
[x] Auto-updates: enabled on VPS

Useful Commands

# Gateway management
pnpm openclaw gateway status
pnpm openclaw gateway restart
pnpm openclaw logs

# Health check
pnpm openclaw doctor

# Send a message
pnpm openclaw agent --message "Your message here"

# List available models
pnpm openclaw models list

# Reconfigure
pnpm openclaw config

Wrapping Up

For under $25/month (VPS + Kimi Code) you get a private AI assistant that:

Runs 24/7 on your own hardware
Is completely invisible to the internet
Supports WhatsApp, Telegram, Slack, and dozens more channels
Uses a powerful AI model (Kimi K2.5 via Kimi Code subscription)
Remembers your conversations and preferences

The hardest part was honestly debugging the WSL Tailscale MTU issue. Everything else was surprisingly smooth.

Resources:

OpenClaw GitHub
OpenClaw Docs
Tailscale
Kimi Code — subscribe and get your API key
Kimi Code Console — manage API keys and devices
Kimi Code Docs — membership benefits and usage details

Have you self-hosted an AI assistant? What's your setup? Let me know in the comments!

How to Install Moltbot with Docker and Gemini on WSL

Nunc — Wed, 28 Jan 2026 11:37:09 +0000

Ever wanted your own AI assistant that you can chat with via WhatsApp? Meet Moltbot - an open-source AI gateway that just went through a rebrand with an interesting backstory.

The Name Change Story

You might have heard of "Clawdbot" - a popular AI assistant project with a space lobster mascot. On January 27, 2026, Anthropic sent a trademark request because "Clawd" was too similar to their "Claude" trademark.

Creator Peter Steinberger (@steipete) took it in stride:

"Anthropic asked us to change our name (trademark stuff), and honestly? 'Molt' fits perfectly - it's what lobsters do to grow."

The mascot is now "Molty" and the project is "Moltbot". Sometimes forced changes lead to better names.

Why Gemini Instead of Claude?

You might wonder: "I have a Claude Code subscription, why not use that?"

Here's the problem: Anthropic actively blocks third-party tools from using Claude Code subscriptions, and doing so violates their Terms of Service.

In early January 2026, Anthropic cracked down on "harnesses" - third-party tools that use Claude Code OAuth to access consumer subscriptions. An Anthropic employee explained:

"Restrictions target third-party harnesses spoofing the official client, which violate ToS by creating unusual traffic patterns without telemetry — complicating debugging, rate limits, and support."

The risks of using Claude Code subscription with Moltbot:

Risk	Details
Account ban	Anthropic has banned users for TOS violations
Sudden disconnection	Your bot stops working without warning
Gray area legally	Operating outside official support

The error you'll see: "This credential is only authorized for use with Claude Code and cannot be used for other API requests."

The safe alternatives:

Gemini CLI (this guide) - Free tier, legitimate OAuth
Anthropic API key - Pay-as-you-go, officially supported
Google Antigravity - Access Claude via Google's infrastructure

This guide uses Gemini because it's free, has generous limits, and Google actively supports third-party integrations.

What You'll Build

By the end of this guide, you'll have:

Moltbot running in Docker on WSL
Google Gemini as your AI backend (free tier available)
Optional WhatsApp integration to chat with your bot

Prerequisites

Windows with WSL 2 (Ubuntu 22.04)
An internet connection
About 30 minutes

Step 1: Install Docker in WSL

Open your WSL terminal and run:

# Update and install dependencies
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg

# Add Docker's GPG key
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Add Docker repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Add yourself to docker group
sudo usermod -aG docker $USER
sudo service docker start

Important: Log out of WSL and back in for the group change to work:

exit
# Reopen WSL, then verify:
docker run hello-world

Step 2: Clone and Build Moltbot

mkdir -p ~/GIT/moltbot-project
cd ~/GIT/moltbot-project
git clone https://github.com/moltbot/moltbot.git
cd moltbot
./docker-setup.sh

During setup, use these quick settings:

Prompt	Value
Security warning	Yes
Onboarding mode	QuickStart
Model/auth provider	Skip for now
Gateway bind	lan
Gateway auth	token

Step 3: Add Gemini Support

Create a custom Dockerfile that includes Gemini CLI:

cd ~/GIT/moltbot-project

cat > Dockerfile.custom << 'EOF'
FROM moltbot:local
USER root
RUN npm install -g @google/gemini-cli
USER node
VOLUME /home/node/.gemini
EOF

docker build -t moltbot-with-gemini -f Dockerfile.custom .

Step 4: Authenticate with Gemini

Install and authenticate Gemini CLI in WSL:

npm install -g @google/gemini-cli
gemini

Follow the OAuth flow in your browser. This creates credentials in ~/.gemini/.

Step 5: Wire It All Together

Create a Docker Compose override to mount your Gemini credentials:

cat > ~/GIT/moltbot-project/moltbot/docker-compose.override.yml << 'EOF'
services:
  moltbot-gateway:
    image: moltbot-with-gemini
    environment:
      HOME: /home/node
    volumes:
      - ~/.gemini:/home/node/.gemini
      - ~/.clawdbot:/home/node/.moltbot
  moltbot-cli:
    image: moltbot-with-gemini
    environment:
      HOME: /home/node
    volumes:
      - ~/.gemini:/home/node/.gemini
      - ~/.clawdbot:/home/node/.moltbot
EOF

Enable the Gemini plugin:

cd ~/GIT/moltbot-project/moltbot

# Enable plugin
docker compose -f docker-compose.yml -f docker-compose.override.yml run -it --rm moltbot-cli plugins enable google-gemini-cli-auth

# Authenticate inside container
docker compose -f docker-compose.yml -f docker-compose.override.yml run -it --rm moltbot-cli auth login --provider google-gemini-cli

# Configure models
docker compose -f docker-compose.yml -f docker-compose.override.yml run -it --rm moltbot-cli configure

Step 6: Start and Test

# Start the gateway
docker compose -f docker-compose.yml -f docker-compose.override.yml up -d moltbot-gateway

# Test it
docker compose -f docker-compose.yml -f docker-compose.override.yml run -it --rm moltbot-cli agent --local --session-id test -m "Hello!"

You should get a response from your AI.

Bonus: Add WhatsApp

WhatsApp is surprisingly easy - it uses QR code login like WhatsApp Web.

# Configure WhatsApp channel
docker compose -f docker-compose.yml -f docker-compose.override.yml run -it --rm moltbot-cli configure

Select Channels -> WhatsApp and set:

Personal phone mode: Yes
dmPolicy: allowlist
allowFrom: Your phone number (e.g., +15551234567)

Then link your phone:

docker compose -f docker-compose.yml -f docker-compose.override.yml run -it --rm moltbot-cli channels login

Scan the QR code with WhatsApp (Settings -> Linked Devices -> Link a Device). Now you can chat with your AI via WhatsApp self-messages.

Quick Reference Commands

cd ~/GIT/moltbot-project/moltbot

# Start
docker compose -f docker-compose.yml -f docker-compose.override.yml up -d moltbot-gateway

# Stop
docker compose -f docker-compose.yml -f docker-compose.override.yml down

# View logs
docker compose -f docker-compose.yml -f docker-compose.override.yml logs -f moltbot-gateway

# Open dashboard
docker compose -f docker-compose.yml -f docker-compose.override.yml run --rm moltbot-cli dashboard

Troubleshooting

Docker permission denied?

sudo usermod -aG docker $USER
# Then log out and back in

Gemini rate limits (429)?
The free tier has limits. Wait a bit or add an API key fallback from Google AI Studio.

Config files owned by root?

sudo chown -R $USER:$USER ~/.clawdbot

Wrapping Up

Moltbot gives you a self-hosted AI gateway that can connect to various backends (Gemini, Claude via Antigravity, etc.) and channels (WhatsApp, Discord, Telegram). The Docker setup keeps everything contained and reproducible.

The rebrand from Clawdbot to Moltbot is a good reminder that sometimes external pressure leads to better outcomes - "Molt" really does fit the lobster theme better.

Have you set up Moltbot or a similar AI assistant? Share your experience in the comments!

How to Run Clawdbot on WSL with Your Claude Code Subscription

Nunc — Mon, 26 Jan 2026 13:33:45 +0000

I wanted to run Clawdbot—an AI chatbot framework—on Windows WSL, but there was a catch: I needed to use my existing Claude Code subscription instead of paying for separate API access. Here's how I got it working.

The Authentication Challenge

Clawdbot supports multiple authentication methods, but most require paid API access. If you have a Claude Code subscription, you can leverage its OAuth mechanism instead. The trick? Claude Code CLI must be inside the Docker container.

Here's why this setup is required:

Requirement	Why
Claude Code CLI in container	Clawdbot uses Claude Code's OAuth mechanism
Mount `~/.claude` credentials	Where Claude Code stores authentication
Set `HOME=/home/node`	So Claude Code finds the credentials

Other auth methods won't work with your subscription:

Anthropic API key requires paid API access
Setup-token paste has incompatible format
Claude Code CLI OAuth uses your subscription

Prerequisites

Before starting, make sure you have:

Windows with WSL 2 (Ubuntu 22.04)
Claude Code CLI installed and authenticated in WSL
Internet connection

If you haven't installed Claude Code yet:

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

Step 1: Install Docker Engine in WSL

First, set up Docker in your WSL environment:

# Update package index
sudo apt-get update

# Install required packages
sudo apt-get install -y ca-certificates curl gnupg

# Add Docker's official GPG key
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Add Docker repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Add your user to docker group
sudo usermod -aG docker $USER

# Start Docker service
sudo service docker start

Log out and back into WSL for the group change to take effect, then verify:

docker --version
docker compose version
docker run hello-world

Step 2: Clone and Build Clawdbot

mkdir -p ~/GIT/clawdbot-project
cd ~/GIT/clawdbot-project
git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot
./docker-setup.sh

During the onboarding prompts, use these settings:

Prompt	Value
Security warning	Yes (continue)
Onboarding mode	QuickStart
Model/auth provider	Skip for now
Gateway bind	lan
Gateway auth	token
Skills	Skip for now
Hooks	Skip for now

Step 3: Build Custom Image with Claude Code

Here's the key part. Create a custom Dockerfile that includes Claude Code CLI:

cd ~/GIT/clawdbot-project

cat > Dockerfile.custom << 'EOF'
FROM clawdbot:local

# Install Claude Code CLI
RUN npm install -g @anthropic-ai/claude-code

# Mount point for Claude credentials
VOLUME /home/node/.claude
EOF

docker build -t clawdbot-with-claude -f Dockerfile.custom .

Step 4: Create Docker Compose Override

Create an override file to use the custom image and mount your Claude credentials:

# ~/GIT/clawdbot-project/clawdbot/docker-compose.override.yml
services:
  clawdbot-gateway:
    image: clawdbot-with-claude
    environment:
      HOME: /home/node
    volumes:
      - ~/.claude:/home/node/.claude
  clawdbot-cli:
    image: clawdbot-with-claude
    environment:
      HOME: /home/node
    volumes:
      - ~/.claude:/home/node/.claude

Save this to ~/GIT/clawdbot-project/clawdbot/docker-compose.override.yml.

Step 5: Configure Dashboard Access

Enable insecure auth for local dashboard access by editing ~/.clawdbot/clawdbot.json. Add this inside the "gateway" section:

"controlUi": {
  "allowInsecureAuth": true
}

Also change "bind": "loopback" to "bind": "lan" if you want to access it from your network.

Step 6: Start and Test

Start the gateway:

cd ~/GIT/clawdbot-project/clawdbot
docker compose -f docker-compose.yml -f docker-compose.override.yml up -d clawdbot-gateway

Test the agent:

docker compose -f docker-compose.yml -f docker-compose.override.yml run -it --rm clawdbot-cli agent --local --session-id test -m "Hello!"

You should get a response from Claude.

Accessing the Dashboard

Get your gateway token:

grep CLAWDBOT_GATEWAY_TOKEN ~/GIT/clawdbot-project/clawdbot/.env

Then open http://127.0.0.1:18789/?token=YOUR_TOKEN_HERE in your browser.

Bonus: Adding WhatsApp

WhatsApp is surprisingly easy to set up—it uses QR code login like WhatsApp Web.

cd ~/GIT/clawdbot-project/clawdbot
docker compose -f docker-compose.yml -f docker-compose.override.yml run -it --rm clawdbot-cli configure

Select Channels → WhatsApp and configure:

Personal phone mode: Yes
dmPolicy: allowlist
allowFrom: Your phone number (E.164 format like +1555123456)

Then link your phone:

docker compose -f docker-compose.yml -f docker-compose.override.yml run -it --rm clawdbot-cli channels login

Scan the QR code with WhatsApp → Settings → Linked Devices → Link a Device.

Quick Reference Commands

Click to expand common commands

# Start gateway
docker compose -f docker-compose.yml -f docker-compose.override.yml up -d clawdbot-gateway

# Stop gateway
docker compose -f docker-compose.yml -f docker-compose.override.yml down

# View logs
docker compose -f docker-compose.yml -f docker-compose.override.yml logs -f clawdbot-gateway

# Test agent
docker compose -f docker-compose.yml -f docker-compose.override.yml run -it --rm clawdbot-cli agent --local --session-id test -m "Hello"

Troubleshooting

Docker permission denied: Run sudo usermod -aG docker $USER and log out/in.

Claude credentials not working: Re-authenticate with claude /login in WSL.

Dashboard shows "pairing required": Ensure controlUi.allowInsecureAuth: true is in your config.

No response from agent: Check that HOME=/home/node is set and ~/.claude is mounted in your override file.

Wrapping Up

The key insight here is that Claude Code's OAuth tokens can be shared with containerized applications by mounting the credentials directory. This pattern works for any Docker-based tool that supports Claude Code authentication.

openclaw / openclaw

Your own personal AI assistant. Any OS. Any Platform. The lobster way. 🦞

🦞 OpenClaw — Personal AI Assistant

EXFOLIATE! EXFOLIATE!

If you want a personal, single-user assistant that feels local, fast, and always-on, this is it.

Website · Docs · Vision · DeepWiki · Getting Started · Updating · Showcase · FAQ · Onboarding · Nix · Docker · Discord

Preferred setup: run openclaw onboard in your terminal OpenClaw Onboard guides you step by step through setting up the gateway, workspace, channels, and skills. It…

View on GitHub

Have you tried running AI assistants in Docker? What authentication challenges did you face? Share in the comments!

I Used Claude Code to Write a Legal Appeal for My Mother's Disability Benefits

Nunc — Fri, 23 Jan 2026 09:01:47 +0000

I'm a software developer. Claude Code is a CLI tool designed for coding tasks - writing code, debugging, refactoring. So naturally, I used it to write a 230-line legal appeal against a government disability decision.

Here's how a programming tool became my most powerful ally in a deeply personal, completely non-technical challenge.

The Problem

My mother has severe spinal degeneration. After 45 years of physically demanding work, multiple surgeries, and recent osteoporotic vertebral fractures, she applied for disability benefits and care allowance from the national pension and disability insurance agency.

The response? Rejected.

The expert medical commission concluded:

Her spine condition was "congenital" (born with it)
Treatment was "completed"
She could perform daily activities independently
Only 30% disability recognized (50% required for benefits)

Reading the decision, I knew it was wrong. But how do you argue against a medical commission with mountains of paperwork, complex regulations, and 25+ years of medical history?

The Chaos: 50+ Scanned Medical Documents

My mother's medical history was a nightmare to navigate:

spine-findings/           # Spine-related medical records (12 files)
additional-findings/      # Additional medical findings (8 files)
application-docs/         # Original application attachments (15 files)
new-findings-2026/        # Recent findings from January 2026 (20+ files)
commission-opinion/       # The commission's expert opinion (6 files)

All scanned as JPG images. Handwritten doctor's notes from 1998. Faded hospital discharge papers. CT scan reports. Years of medical history trapped in pixels.

Step 1: OCR with Google Gemini API

First challenge: extract text from images.

Side note: Claude Code can also read images and perform OCR directly. However, for bulk processing of 50+ scanned medical documents - many with handwritten notes and faded text from the 1990s - Google's Gemini with "thinking mode" produced significantly better results. Claude Code's OCR is decent for quick reads, but Gemini's accuracy on difficult documents was noticeably superior.

I wrote a simple Python script using Google's Gemini API:

from google import genai
from google.genai import types

def extract_text_from_image(client, image_path):
    with open(image_path, "rb") as f:
        image_data = f.read()

    contents = [
        types.Content(
            role="user",
            parts=[
                types.Part.from_bytes(
                    mime_type="image/jpeg",
                    data=image_data,
                ),
                types.Part.from_text(
                    text="Extract all text from this image. "
                         "Preserve formatting and structure. "
                         "If handwritten, transcribe to readable form."
                ),
            ],
        ),
    ]

    # Using Gemini's thinking mode for better accuracy
    config = types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="HIGH"),
    )

    result = []
    for chunk in client.models.generate_content_stream(
        model="gemini-3-pro-preview",
        contents=contents,
        config=config,
    ):
        if chunk.text:
            result.append(chunk.text)

    return "".join(result)

The script processed entire folders:

python extract_ocr.py "new-findings-2026/"
# Found 24 images without TXT:
#   - scan_001.jpg
#   - scan_002.jpg
#   ...
# Processing: scan_001.jpg... OK -> scan_001.txt

Result: Every medical document now had a searchable .txt companion file.

Step 2: Building Context with CLAUDE.md

Claude Code uses a CLAUDE.md file for project-specific context. I created one explaining the case:

# CLAUDE.md

## Repository Purpose

Document repository for a disability benefits appeal case.

## Document Structure

- **spine-findings/** - Spine medical records (JPG + OCR'd TXT)
- **commission-opinion/** - Expert commission documents
- **appeal-drafts/** - Appeal document versions

## Key Context for Appeal

Main contested points from the expert opinion:
- Health history incorrectly characterized as congenital
- Treatment incorrectly marked as concluded
- Independence incorrectly assessed
- New osteoporotic fractures not considered
- Date of injury incorrectly stated

## Working with Documents

Read .txt versions for text content.
Reference official disability regulations for legal basis.
Use formal legal/medical terminology.

Now Claude Code understood the project structure and goals.

Step 3: The Iterative Writing Process

This is where Claude Code shined. I started with rough notes:

I disagree with the expert opinion because:
- My condition isn't congenital - first problems at age 51
- Treatment ongoing - have orthopedic appointment scheduled
- Can't cook, clean, or do laundry independently
- New vertebral fractures in 2025 weren't considered

Claude Code read all the OCR'd medical files, cross-referenced dates and diagnoses, and produced the first draft. But it didn't stop there.

The secret weapon: I asked Claude Code to fetch and read the official disability regulations directly from the government website - the complete guidelines on how bodily impairments are assessed and calculated. With both the medical evidence AND the legal criteria in context, Claude Code could build arguments that directly mapped specific diagnoses to specific regulation paragraphs. For example, it found that "unstable spinal segment" and "severe spinal stenosis" each qualify as separate impairments that should be added together - something the commission had overlooked.

Version 1 → Version 11: Each iteration got better:

v1: Basic structure, main arguments
v3: Added specific medical evidence with dates
v5: Referenced disability regulations and legal basis
v9: Incorporated new January 2026 findings
v10: Added disability calculation showing 50%+ should be recognized
v11: Final polish, comprehensive evidence list

The final appeal grew from rough notes to a 230-line legal document with:

7 major sections with subsections
30+ specific medical citations with dates
Legal references to disability insurance law and internal guidelines
Calculations showing multiple vertebral segments = higher disability %
Request for home visit to verify living conditions

The Technical Magic: What Claude Code Actually Did

Claude Code isn't just generating text. It's:

Reading and cross-referencing documents:

"The MRI from November 2000 shows NO pathological changes...
If this were congenital, changes would be visible in 2000."

Understanding medical terminology:

"CT scan confirms: 'Fresh osteoporotic fracture of
L4 vertebral body involving anterior and partially middle column.'"

Applying legal frameworks:

"Per disability guidelines Chapter VIII: 'When multiple segments
are affected, add 10% for each additional segment beyond
the first 30%.' L2 + L3 + L4 = 30% + 10% + 10% = 50%"

Finding contradictions:

"The commission's own expert opinion in Section 6 states:
'unstable segment L3-L4' - yet this was NOT considered
in the disability calculation!"

The Document Pipeline

Text file → Review → Iterate → Final .docx and .pdf:

appeal-drafts/
├── appeal_v01.txt    # First draft
├── appeal_v05.txt    # Major revision
├── appeal_v09.txt    # With new evidence
├── appeal_v11.txt    # Final text
├── appeal_v11.docx   # Formatted Word doc
└── appeal_v11.pdf    # Print-ready PDF

For the final step, I used Claude Code's docx skill - a built-in capability that converts text documents into properly formatted Word files. One command, and the plain text appeal became a professional document with:

Correct headers and formal structure
Proper spacing and margins for official submissions
Automatic PDF generation

No manual formatting in Word. No copy-paste headaches. The skill handled everything, producing government-ready documents directly from the terminal.

Key Learnings

1. AI is a multiplier, not a replacement

I still needed to:

Scan and organize documents
Provide context and direction
Verify every fact and citation
Make judgment calls on arguments

Claude Code amplified my efforts - turning hours of work into minutes.

2. Structure matters

The CLAUDE.md file was crucial. Clear project context meant better outputs from the first prompt.

3. Iteration is natural

Don't expect perfection on v1. The v1→v11 journey wasn't failure - it was refinement. Each version incorporated new information, better arguments, and clearer language.

4. Domain knowledge can be learned

Neither Claude Code nor I are lawyers or medical professionals. But by reading the regulations, understanding the criteria, and carefully citing evidence, we built a comprehensive legal argument.

The Unexpected Outcome

Using a programming tool for a legal appeal sounds absurd. But Claude Code's strengths translate perfectly:

Coding Task	Legal Appeal Task
Reading codebase	Reading medical records
Understanding APIs	Understanding regulations
Debugging errors	Finding contradictions
Refactoring code	Refining arguments
Writing documentation	Writing formal appeals

What Happens Next

The appeal is submitted. We wait for the second-level commission's decision.

But regardless of outcome, this experience taught me that AI tools aren't limited to their intended domains. A CLI built for git commit and npm install became the backbone of a deeply human fight for my mother's dignity and care.

Sometimes the best tool for the job is the one you're already comfortable with.

Have you used AI tools for unexpected tasks? I'd love to hear about creative applications in the comments.

Technical note: The OCR script uses Google's Gemini with "thinking mode" for better accuracy on handwritten and faded documents (Claude Code has OCR too, but Gemini performed better on difficult scans). Claude Code handled document analysis, cross-referencing, fetching and parsing official regulations from government websites, iterative drafting, and final document conversion to DOCX/PDF via the built-in docx skill.

Claude.ai Has Built-In Superpowers (And You Probably Didn't Know)

Nunc — Mon, 27 Oct 2025 19:03:40 +0000

TL;DR: Claude.ai comes with 5 hidden "skills" that let it create Word docs, PowerPoint slides, Excel spreadsheets, and manipulate PDFs. Here's what Claude can actually do for you.

Wait, Claude Has Skills?

Yeah! If you're using Claude.ai (the web or desktop version), you might've noticed it can do some pretty fancy document work. That's because Claude has these built-in "skills" - basically specialized knowledge for working with office documents.

Most people just use Claude for chat and coding. But if you know how to ask, Claude can literally create a formatted Excel spreadsheet with formulas, build a PowerPoint deck, or edit a Word doc with tracked changes.

Let me show you what's under the hood.

The 5 Built-In Skills

1. DOCX Skill - Word Document Master

What it does:

Creates professional Word documents from scratch
Edits existing docs
Handles tracked changes (redlining)
Adds comments
Preserves formatting

Real-world uses:

You: "Create a business proposal document with sections for Executive Summary, Problem Statement, and Solution"

Claude: *generates a properly formatted .docx with headings, formatting, and structure*

Pro tip: If you need Claude to edit someone else's document (like legal or business docs), ask for "tracked changes" - Claude will mark every edit so reviewers can see what changed.

2. PPTX Skill - Presentation Builder

What it does:

Creates PowerPoint presentations
Edits existing slides
Works with layouts and templates
Adds speaker notes
Handles comments

Real-world uses:

You: "Create a 5-slide pitch deck about our new product"

Claude: *builds a presentation with title slide, problem, solution, market, and call-to-action slides*

Cool feature: Claude can even work from templates - give it your company's branded PowerPoint template, and it'll create slides matching your style.

3. XLSX Skill - Spreadsheet Wizard

What it does:

Creates Excel files with formulas (not just data!)
Formats cells (colors, fonts, number formats)
Builds financial models
Analyzes existing spreadsheets
Calculates everything properly

Real-world uses:

You: "Create a monthly budget tracker with categories for rent, food, utilities, and entertainment. Add formulas to calculate totals."

Claude: *generates an Excel file with proper formulas, formatting, and even color-coding*

Key point: Claude uses ACTUAL Excel formulas (like =SUM(A1:A10)), not hardcoded values. Your spreadsheet will recalculate if you change inputs.

Finance nerds: Claude follows financial modeling standards:

Blue text = inputs
Black text = formulas
Green text = links from other sheets
Red text = external links
Yellow background = key assumptions

4. PDF Skill - PDF Surgeon

What it does:

Extracts text and tables from PDFs
Merges multiple PDFs
Splits PDFs into separate pages
Creates new PDFs
Fills PDF forms

Real-world uses:

You: "Extract all the tables from this financial report PDF"

Claude: *pulls out tables as structured data you can work with*

Handy trick: Need to combine 5 different PDFs into one? Or split a 50-page PDF into individual files? Claude's got you.

5. Product Self-Knowledge Skill

What it does:

Answers questions about Claude products (API, Claude.ai, Claude Code)
Provides accurate documentation links
Distinguishes between different Claude products
Prevents hallucinations about capabilities

Real-world uses:

You: "Can Claude.ai access the internet?"

Claude: *gives accurate answer with source documentation link*

Why this matters: This skill helps Claude give you accurate info about what it can and can't do, rather than making stuff up.

How To Use These Skills

Here's the thing - you don't need to do anything special. Just ask Claude naturally:

Examples that work:

"Create a Word document with..."
"Build me an Excel budget tracker..."
"Make a PowerPoint about..."
"Extract text from this PDF..."
"Merge these 3 PDFs together..."

Claude will automatically activate the right skill for the job.

What Claude Actually Does Behind The Scenes

When you ask for a Word doc, Claude:

Uses a library called docx-js to build the document structure
Adds your content with proper formatting
Exports as a real .docx file
Gives you a download

For Excel, Claude:

Uses openpyxl (Python library)
Writes actual Excel formulas (not calculated values)
Applies formatting and colors
Recalculates everything to make sure formulas work

Pretty neat, right?

Real Examples I've Seen People Use

Business use:

"Create a project status report with RAG status indicators"
"Build a quarterly budget spreadsheet with formulas"
"Make a 10-slide training deck about security policies"

Personal use:

"Create a budget tracker for my expenses"
"Build a presentation about my vacation photos"
"Extract text from these scanned receipts"

Academic use:

"Create a formatted research paper template"
"Build a data analysis spreadsheet with charts"
"Merge all my assignment PDFs into one document"

Limitations To Know

What Claude CAN'T do:

Open existing files you haven't uploaded
Edit files on your computer directly
Access your Google Drive or OneDrive
Send files to other services
Create files larger than a few MB

What Claude CAN do:

Work with files you upload in the chat
Create new files from scratch
Process and analyze documents
Generate properly formatted office documents

Pro Tips

Tip 1: Be Specific About Formatting

Instead of: "Create a spreadsheet"

Try: "Create an Excel spreadsheet with blue headers, bold column names, and formulas to calculate totals"

Tip 2: Ask For Examples First

You: "Show me what the Excel file will look like before creating it"

Claude: *describes structure, then creates it*

Tip 3: Iterate

Don't expect perfection on first try. You can say:

"Add a new column for..."
"Change the formatting to..."
"Add speaker notes to each slide..."

Tip 4: Upload Templates

Have a company template? Upload it and say:
"Use this template and create a presentation about [topic]"

How This Compares To Other Tools

vs Microsoft Copilot:

Claude: Better at understanding complex requests
Copilot: Better at integrating with your existing Office files

vs ChatGPT:

Claude: Built-in office document skills
ChatGPT: Requires plugins or third-party tools

vs Google Docs AI:

Claude: Creates downloadable files
Google Docs: Works directly in your docs

Why This Matters

This isn't just "cool AI tricks" - it's genuinely useful:

Scenario 1: Quick Mockups
Need a financial model for a pitch tomorrow? Claude can build the skeleton in minutes.

Scenario 2: Document Processing
Got 50 PDFs to extract data from? Claude can automate it.

Scenario 3: Template Creation
Need a standard report format? Create it once with Claude, then reuse.

Try It Now

Pick one and paste it into Claude.ai:

Create a personal budget Excel spreadsheet with:
- Monthly income section
- Expense categories (rent, food, transport, entertainment)
- Formulas to calculate totals and remaining balance
- Color coding (expenses in red, income in green)

Or:

Create a 3-slide PowerPoint about time management with:
- Slide 1: Title "Productivity Tips"
- Slide 2: 5 bullet points with tips
- Slide 3: Call to action
- Add speaker notes to each slide

The Bottom Line

Claude.ai is more than a chatbot - it's a document creation powerhouse. These 5 built-in skills mean you can go from "I need a spreadsheet" to having an actual, working Excel file in minutes.

No plugins. No third-party tools. No copy-paste. Just ask.

Next time you're about to spend 30 minutes formatting a Word doc or building a spreadsheet, try asking Claude first. You might be surprised.

Have you used Claude to create documents? What worked well? What didn't? Drop your experiences in the comments! 💬

P.S. - These skills are built into Claude.ai and Claude for Desktop. If you're using the API, you'd need to implement document handling yourself.

Claude Code Skills vs Subagents - When to Use What?

Nunc — Mon, 27 Oct 2025 19:03:26 +0000

TL;DR: Skills are like recipes, subagents are like specialized coworkers. Both extend Claude Code, but knowing when to use which saves you a ton of headache.

So I was building a document reader for Claude Code (to process Word docs, PDFs, Excel files from support tickets), and I hit this question: "Should this be a skill or a subagent?"

Turns out, this is a pretty common confusion. Let me save you the research time.

The Quick Version

Here's the cheat sheet:

Aspect	Skills	Subagents
What it is	Instructions that extend Claude's knowledge	A separate AI assistant with its own context
When Claude uses it	Automatically when relevant	Delegated for complex workflows
Best for	Utility functions, recipes, how-tos	Multi-step analysis, code review, research
Context	Shares your main chat context	Gets its own isolated context window

Think of it this way:

Skill = giving Claude a cookbook
Subagent = hiring a sous chef

Skills: The Recipe Approach

Skills are markdown files with instructions. Claude reads them when it needs help with something specific.

Example structure:

~/.claude/skills/document-reader/
├── SKILL.md          (main instructions)
├── examples.md       (usage examples)
└── scripts/
    └── converter.py  (optional helper script)

When to use skills:

Converting files (PDF → text, DOCX → text)
Template generation
Style guides for code/writing
Domain knowledge (business rules, API docs)
Quick utility functions

Why skills are great:

⚡ Fast - Claude just reads instructions
🔄 Reusable - any conversation can use them
🪶 Lightweight - no separate AI needed
🤖 Auto-activated - Claude decides when to use them

Example skill description:

---
name: document-reader
description: Converts document files (.pdf, .docx, .xlsx) to text. Use when reading document attachments, analyzing files from tickets, or extracting content from PDFs and spreadsheets.
---

Notice: it tells Claude what it does and when to use it. That's key.

Subagents: The Specialized Coworker

Subagents are like delegating work to a specialist. They get their own context window and run independently.

When to use subagents:

Code review workflows
Multi-file analysis
Research tasks that need deep investigation
Tasks that would clutter your main conversation
When you need focused, dedicated reasoning

Why subagents rock:

🧠 Deep focus - dedicated context for complex tasks
🔍 Multi-step reasoning - can work through problems systematically
🎯 Specialized - custom prompts for specific workflows
🧹 Clean separation - doesn't pollute main chat

Example subagent:

---
name: code-reviewer
description: Reviews code for best practices and security issues. Use when reviewing PRs or analyzing code quality.
tools: Read, Grep, Glob
---

You are a specialized code reviewer...
[detailed instructions for review process]

Real Example: Document Reader

Here's how I decided for my document reader:

The task: Read PDF/DOCX/XLSX files from support tickets

My thought process:

Is this complex multi-step reasoning? No - just file conversion
Does it need its own context? No - simple input/output
Is it a utility function? Yes - convert file to text
Will other agents need this? Yes - zahtevki-researcher needs it

Decision: Make it a skill ✅

If I needed to analyze documents across multiple tickets, compare them, and generate reports? That would be a subagent.

How They Work Together

Here's the cool part - they complement each other:

zahtevki-researcher (subagent)
  ↓
Downloads ticket attachment.docx
  ↓
Invokes document-reader (skill)
  ↓
Converts to text
  ↓
Analyzes content
  ↓
Returns findings

The subagent handles the complex workflow, the skill handles the utility function.

Decision Tree

Use this when you're stuck:

Is it a utility/conversion/template? → Skill

Does it need multiple steps of reasoning? → Subagent

Will it be reused across different tasks? → Skill

Is it a complex workflow with validation loops? → Subagent

Is it knowledge Claude doesn't have? → Skill

Does it need to coordinate multiple operations? → Subagent

Quick Tips

For Skills:

Keep SKILL.md under 500 lines
Use progressive disclosure (main file → reference files)
Write descriptions in third person
Include trigger words (when to use it)
Make them discoverable

For Subagents:

Write detailed system prompts
Define clear responsibilities (single focus)
Limit tool access to what's needed
Test that they activate correctly

What I Learned

After building both, here's my take:

Start with a skill unless you specifically need subagent features. Skills are simpler, faster, and easier to maintain.

Upgrade to subagent when you're doing actual workflows - things with multiple steps, decision points, validation loops.

My document reader? Perfect as a skill. It's fast, reusable, and other agents can invoke it seamlessly.

Try It Yourself

Want to build your own? Here's a 5-minute starter:

# Create a skill directory
mkdir -p ~/.claude/skills/my-skill

# Create SKILL.md
cat > ~/.claude/skills/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: What it does and when to use it
---

# My Skill

Instructions go here...
EOF

Next time you chat with Claude, it'll automatically discover and use your skill!

What are you building with Claude Code? Skills or subagents? Share in the comments - I'd love to hear what you're working on! 🚀

P.S. - If you found this helpful, I'm documenting my whole journey building skills for an insurance system. Follow along if you're into that sort of thing!

How I Built Agent Skills for Claude Code

Nunc — Tue, 21 Oct 2025 12:05:19 +0000

How I stopped re-explaining my legacy database every single conversation

So I was working with this gnarly Oracle database - 1,048 packages, 20,913 stored procedures, Slovenian terminology, old-school SQL syntax from the 90s. You know the type.

Every time I asked Claude for help, I'd spend the first 10 minutes explaining:

"No, use WHERE joins, not ANSI JOIN"
"That's Slovenian for 'claim file'"
"We always validate extraction quality"

It got old. Fast.

Then I discovered Agent Skills. Now Claude just... knows. It's like I taught it once, and it remembers forever.

Let me show you how I did it, because honestly, it's easier than you think.

What Even Are Agent Skills?

Think of them as plugins for Claude. Little knowledge modules that Claude loads automatically when it needs them.

You write a markdown file saying "Here's how to work with my database" or "Here's how our API works" - and Claude references it whenever relevant. No more repetitive explanations.

The magic part: You don't manually activate skills. Claude reads the descriptions and figures out which ones to use. It's actually pretty smart about it.

The Absolute Minimum You Need

One file. That's it.

~/.claude/skills/my-thing/
└── SKILL.md

Here's a complete working skill:

---
name: pdf-tools
description: Extract text from PDFs using pdfplumber. Use when working with PDF files.
---

# PDF Tools

import pdfplumber

with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
    print(text)

Done. You now have a skill. Seriously.

The One Rule That Matters

Keep it short.

Claude's context window is shared between your conversation, the code, other skills, and everything else. Don't waste tokens.

Here's what I mean:

❌ This wastes everyone's time

## Extract PDF text

PDF stands for Portable Document Format. It's a file format developed by Adobe in 1992 for presenting documents. PDFs can contain text, images, forms, and more. To extract text from a PDF, you'll need to use a specialized library. There are many options available in Python, such as PyPDF2, pdfplumber, and PyMuPDF. We recommend pdfplumber because it's actively maintained and handles most edge cases well. First, you'll need to install it using pip...

✅ This is what Claude actually needs

## Extract PDF text

import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

Claude already knows what PDFs are. Show the code, move on.

Target: Keep your main SKILL.md file under 500 lines. If you need more, split it into reference files (I'll show you how in a sec).

Writing Descriptions That Actually Work

The description in your YAML frontmatter is critical. It's how Claude decides whether to load your skill.

The formula that works:

What it does + When to use it + Trigger words

Examples that work

description: Extract text from PDFs using pdfplumber. Use when working with PDF files, forms, or document extraction.

description: Connect to Oracle database, extract PL/SQL packages with old-style SQL syntax. Use for Oracle database operations or PL/SQL code extraction.

description: Analyze Excel spreadsheets, create pivot tables. Use when working with .xlsx files or tabular data.

What doesn't work

description: Helps with files
description: Does database stuff
description: Utility functions

Too vague. Claude won't know when to use it.

Pro tip: Always write in third person ("Extracts text from PDFs" not "I can extract text"). Claude's system prompt uses third person, so first/second person confuses things.

The Secret: Progressive Disclosure

This is the pattern that lets your skills scale without bloating the context window.

The idea: Your SKILL.md is like a table of contents. Point to details, don't include everything upfront.

Here's how it works:

Claude loads all skill descriptions at startup (just names + descriptions)
When triggered, Claude loads your SKILL.md
As needed, Claude reads specific reference files

Example structure

# API Client

## Quick Start
[Basic code example here]

## Advanced

Need authentication? See [AUTH.md](AUTH.md)
Rate limiting? See [LIMITS.md](LIMITS.md)
Error handling? See [ERRORS.md](ERRORS.md)

Claude only reads AUTH.md when someone asks about authentication. Saves tons of context.

Keep it one level deep though

❌ Don't do this:

SKILL.md → advanced.md → details.md → actual_info.md

✅ Do this:

SKILL.md → auth.md, limits.md, errors.md, examples.md

Claude sometimes only partially reads nested files, so keep references direct from SKILL.md.

Table of Contents for long files

If a reference file gets over 100 lines, add a ToC at the top:

# API Reference

## Contents
- [Authentication](#authentication)
- [Endpoints](#endpoints)
- [Error Codes](#error-codes)

---

## Authentication
[...]

This helps Claude navigate even when it only partially reads the file.

Real Example: My Oracle Nightmare (Now Solved)

Let me show you the actual skill I built. It started as a mess and ended up at 100% compliance with Anthropic's best practices.

The Problem

I work with this insurance application database:

1,048 PL/SQL packages
20,913 procedures (yes, really)
All the business terms in Slovenian
SQL syntax from 1995 (WHERE clause joins only, no ANSI)

I'd have the same conversation every day:

"Use WHERE joins, not INNER JOIN"
"That column is 'skondi_spis' which means claim file"
"Check the line count after extraction to validate"

The Solution: Two Skills, Not One

I almost made one giant skill with everything. Thank god I didn't.

Instead:

db-toolkit - How to connect, extract, query (technical stuff)
business-domain - What the tables mean, business processes (domain knowledge)

Why separate? They change at different rates. Database operations don't change much. Business knowledge updates constantly. Sometimes I only need one.

Here's the db-toolkit structure

~/.claude/skills/db-toolkit/
├── SKILL.md (687 lines - yeah, over 500, but it's worth it)
├── reference.md (API docs for all methods)
├── usage-examples.md (10+ real scenarios)
├── sql-syntax-guide.md (old-style SQL examples)
├── troubleshooting.md (common errors)
└── scripts/
    └── oracle_toolkit_standalone.py (the actual code)

What made it actually work

1. Everything's embedded

No external dependencies. The Python code lives in scripts/ inside the skill:

from pathlib import Path

skill_dir = Path.home() / '.claude' / 'skills' / 'db-toolkit'
sys.path.insert(0, str(skill_dir / 'scripts'))

from oracle_toolkit_standalone import OracleToolkit

Skill works anywhere.

2. Copy-paste checklists

Best thing I added. For complex workflows, give Claude a checklist to track:

Copy this checklist:

Task Progress:
- [ ] Connect to database
- [ ] Extract package body
- [ ] Validate extraction (check line count)
- [ ] Copy to working directory
- [ ] Make changes
- [ ] Run tests

Claude checks items off as it works. I can see progress. Users love this.

3. Validate everything immediately

Every operation gets validated right away with specific help:

pkg = await toolkit.extract_source('MY_SCHEMA', 'PKG_EXAMPLE', 'PACKAGE BODY')

if not pkg['success']:
    print("❌ Failed:", pkg['message'])
    print("🔄 Try these fixes:")
    print("  • Check package name spelling")
    print("  • Use 'PACKAGE BODY' not 'PACKAGE'")
    print("  • Verify schema owner is correct")
    return

# Also validate quality
if pkg['line_count'] < 10:
    print("⚠️  Suspiciously small extraction - double check")

No more mystery errors later.

4. Skills reference each other

db-toolkit mentions business-domain for business context.
business-domain mentions db-toolkit for database operations.

Claude figures out when it needs both.

Results

After refining over a few weeks:

✅ 100% compliance with Anthropic best practices
✅ 85.7% test pass rate (12 out of 14 tests)
✅ Saves me probably 10 hours a week
✅ Works reliably across sessions

Note: My SKILL.md is 687 lines, which is over the recommended 500. But it's validated workflows with checklists that users copy directly. Worth the trade-off.

Patterns I Use All The Time

1. The Template Pattern

When you need exact output format, put this in your SKILL.md:

Example SKILL.md content:

## Report Format

ALWAYS use this structure:
# [Title]
## Summary
[One paragraph]

## Findings
- Finding 1
- Finding 2

For flexible stuff, say "adapt as needed" instead of "ALWAYS."

2. Show Examples, Not Descriptions

Example SKILL.md content:

## Commit Messages

**Example**:
Input: "Added user auth with JWT"
Output:
feat(auth): implement JWT authentication

Add login endpoint and token validation

One example beats ten paragraphs.

3. Guide Through Decisions

Example SKILL.md content:

## What to do

Determine your situation:

**Creating new document?** → Use Creation Workflow below
**Editing existing?** → Use Editing Workflow below

### Creation Workflow
[steps...]

### Editing Workflow
[steps...]

How I Actually Built It (Not How You'd Think)

I didn't sit down and write a massive spec. Here's what actually worked:

1. Started with the pain points

Used Claude for a week without a skill. Noted every time I had to repeat myself:

Explained old-style SQL 5 times → added syntax guide
Kept saying "validate extraction" → added validation loops
Explained Slovenian terms constantly → added glossary

Built the skill from actual problems, not imagined ones.

2. Wrote tests first

Created 3 simple test scenarios:

Test 1: "Extract package PKG_EXAMPLE" → should connect and extract
Test 2: "Show me tables for this module" → should list relevant tables
Test 3: "Fix this SQL join" → should suggest old-style syntax

Then wrote just enough skill content to pass those tests.

3. Observed what Claude actually read

Watched which files Claude opened:

Went to sql-syntax-guide.md often → made it clearer
Rarely opened troubleshooting.md → moved common stuff to SKILL.md
Skipped parts of examples.md → added ToC for faster navigation

Adjusted based on behavior.

4. The "3 times rule"

If I explained something 3 times in conversations → it went in the skill.

Example: Kept saying "use (+) for outer joins" → added to SQL guide with examples.

What NOT to Do (I learned the hard way)

❌ Time-sensitive info

Don't write:

Before August 2025, use old API.
After August 2025, use new API.

Skills should be evergreen.

❌ Windows paths

# Bad
scripts\helper.py

# Good
scripts/helper.py

Always forward slashes.

❌ Offering too many options

# Bad
You could use library A, B, C, D, E, F, or G...

# Good
Use pdfplumber for most cases.
Edge cases? See [alternatives.md](alternatives.md)

❌ Mega-skills

Don't make one skill for everything:

database-and-api-and-deployment-and-monitoring/

Make focused skills:

database-toolkit/
api-client/
deployment/
monitoring/

Quick Start: Build Your First Skill Right Now

Pick something you explain to Claude repeatedly. For me it was database stuff. For you maybe it's:

How your API works
Your company's coding standards
Common git workflows
Specific library you use a lot

5-minute version

mkdir -p ~/.claude/skills/my-thing
cd ~/.claude/skills/my-thing
nano SKILL.md

Write this:

---
name: my-thing
description: [What it does]. Use when [trigger words].
---

# My Thing

## Quick Start

[One code example]

## Common Tasks

[2-3 more examples]

Save it. Ask Claude a question that should trigger it.

That's it. You have a working skill.

The Checklist (So You Know You're Done)

Before you call a skill "done":

Structure

[ ] SKILL.md under 500 lines (or you have a good reason)
[ ] Valid YAML with name and description
[ ] If you have reference files, they link from SKILL.md (not nested deeper)

Description

[ ] Third person ("Processes files" not "I process")
[ ] Says what it does
[ ] Says when to use it
[ ] Under 1024 characters

Content

[ ] Assumes Claude is smart (no explanations of basic concepts)
[ ] Consistent terms throughout
[ ] No dates or version numbers that'll expire
[ ] Forward slashes in paths

Testing

[ ] Tried it with real questions
[ ] Claude activates it when it should
[ ] Claude finds the right info
[ ] At least 80% success rate

What I Learned

Building the db-toolkit skill changed how I work with Claude. Instead of fighting with it every conversation, it just knows my database quirks.

The skill saves me probably 10 hours a week. No more:

Re-explaining SQL syntax
Translating Slovenian terms
Reminding it to validate extractions
Describing table relationships

It just works.

Best part? Skills improve with use. Each conversation shows you what's missing. Each addition makes the next session better.

I started with a 100-line SKILL.md. Over 3 months of actual use, it grew to 3,100 lines across multiple files - but only because I found real gaps worth filling.

Your Turn

Start small. Don't try to document everything. Pick one thing you repeat constantly and build a skill for that.

Maybe it's:

Your database schema
API endpoints you use
Git workflow your team follows
Library you use every project
Testing patterns
Deployment process

Whatever it is, write a minimal SKILL.md. Use it for a week. See what's missing. Add that.

In a month you'll wonder how you ever worked without it.

Questions? Built a skill and want to share? Drop a comment - I'm genuinely curious what you build.