Build trading bots with AI. Understand every rule.
A local-first workbench for turning trading ideas into visual strategies you can inspect and backtest.

Get started · Website · User guide · Feedback

One idea. Every rule visible.

Describe the trade you have in mind. Catbots helps turn it into a visual flow, so you can follow the conditions, inspect the actions, and test the strategy before deciding what to run.

• Build through conversation. Explain your idea, refine the rules, and compare strategy versions.
• See how it works. Follow the triggers, conditions, and actions in a visual graph.
• Test before deploying. Review backtest results, dataset coverage, and execution traces.
• Keep your workspace local. Bots, configuration, and runtime data live on your computer. You choose the AI provider; chat requests go to that provider.

Catbots currently targets macOS and Hyperliquid perpetual markets. The default release is Strategy Lab Beta. You can create a strategy, inspect its flow, and run a historical backtest. Paper, testnet, and mainnet execution are disabled in this release. Lighter and Aster adapters are planned but are not supported yet.

Quick start

The current installation path is from source. There is no downloadable GitHub Release yet.

You need macOS, Node.js 22.x, pnpm 10.17.1, and access to a supported AI provider. You do not need exchange credentials to create a strategy and run a backtest.

If pnpm is not installed, install the repository's pinned version after setting up Node.js 22:

npm install --global pnpm@10.17.1

Clone and launch Catbots:

git clone https://github.com/catbots-fun/catbots.git
cd catbots
pnpm install
pnpm dev

The first launch builds the native application. When Catbots opens, connect your AI provider and create your first bot.

Try your first strategy

1. Connect AI. Choose a supported provider's sign-in flow and select Use for chat, or enter a compatible API URL, key, and model and select Connect & continue.
2. Create a bot. Select Create new bot, name it, choose Hyperliquid, and select Create draft.
3. Describe your idea. Paste the example below into Chat.
4. Inspect and test. Review Flow, then Backtest. Check the dataset coverage and By market results before approving a revision.

Every hour, for ETH-PERP only, open a long when RSI 14 is below 20.
Close that long when RSI is above 80. Do not open shorts.
Backtest the strategy and explain the results.

This is an example to explore the workflow, not a recommended trading strategy. The AI can propose and test rules. You decide whether to approve a revision.

Note

Strategy Lab Beta does not connect to an exchange or place orders. Paper and Hyperliquid testnet code remain behind a release capability gate while runtime scheduling, recovery, and release validation continue.

Prefer a browser workspace or a UI-only preview?

From the cloned repository, after pnpm install:

Command	What opens
pnpm dev:web	Real browser workspace with a local Electron backend
pnpm dev:all	Browser and desktop together, sharing one backend
pnpm dev:preview	Simulated UI with in-memory demo data; no AI or exchange connection

For the real browser workspace, open http://127.0.0.1:5180/ when the terminal prints Catbots web:. Keep the backend process running. Use dev:all for both surfaces together; do not start separate backends against the same profile.

The preview resets on reload. It does not save credentials, bots, or runtime state. For its address, follow the Vite URL printed in the terminal.

See running Catbots for persistence, lifecycle, and local web details.

Installation troubleshooting

• Wrong Node version: run node --version. Catbots requires v22.x; newer major versions are not supported by the release tooling.
• pnpm not found: install the pinned version above, then check pnpm --version reports 10.17.1.
• Native module compilation fails: install Apple's Command Line Tools with xcode-select --install, then retry pnpm install under Node.js 22.
• Browser port in use: real web mode requires port 5180. Stop the process using that port or launch the desktop with pnpm dev.
• AI connection fails: check the provider URL, credentials, and selected model. See configuration and provider sign-in.

Still stuck? Open an issue with your macOS version, Node version, and redacted error output. Never include API keys or wallet private keys.

Built for strategies you can inspect

Capability	What you can explore
Visual strategy builder	Versioned rules, combined conditions, indicators, and actions
Dynamic markets	Focus on one symbol or screen the selected DEX's active perpetual markets
Backtesting	Deterministic evaluation, per-market results, and execution traces
Execution safety gate	Blocks Paper, exchange connections, and testnet orders in Strategy Lab Beta
Your AI provider	Compatible API endpoints, local models, and supported provider sign-in flows
Community nodes	Install the Funding Filter starter or import reusable subflow manifests

A bot belongs to one DEX. Add a symbol condition such as market.symbol = ETH-PERP when you want to focus on one market. For screeners, each action stays bound to the market being evaluated.

Read the dynamic-market guide or build a reusable node with the Community Node SDK.

Roadmap

Each milestone must deliver a workflow that a user can complete. A milestone is not complete when its UI exists. The workflow must also pass its safety, recovery, and release checks.

Milestone	User outcome	Status
M0 · Local foundation	Create a local profile, connect an AI provider, and keep bot data on the user's computer.	Implemented in source
M1 · AI strategy studio	Describe a strategy in chat, inspect its trigger-condition-action graph, and run a reproducible backtest.	Implemented in source
M2 · Reliable Paper trading	Start and stop a Paper bot, inspect every evaluation and action, and review its performance.	In validation; disabled in Strategy Lab Beta
M3 · Hyperliquid Testnet alpha	Connect a dedicated Agent/API Wallet and test the full order lifecycle with recovery and reconciliation.	In validation; disabled in Strategy Lab Beta
M4 · Public local beta	Install, run, update, and remove the signed macOS app without Node.js or pnpm. Mainnet remains unavailable.	In progress
M5 · Guarded Mainnet	Enable real-money execution only after key custody, risk limits, reconciliation, and recovery pass a separate release review.	Planned
M6 · More perpetual DEX adapters	Add Lighter and Aster through the venue-neutral adapter contract. A bot remains bound to one DEX and can trade any supported perpetual market on that DEX.	Planned
M7 · Data marketplace	Add versioned data providers such as ETF flow with provenance, freshness, permissions, and point-in-time backtest guarantees.	Planned

Hyperliquid remains the reference adapter. Lighter and Aster must pass the same market discovery, order normalization, idempotency, audit logging, and reconciliation tests before Catbots marks either adapter as supported.

Know what you are running

• macOS-only for this release. Windows, Linux, spot, options, and cross-DEX routing are outside the current scope.
• Execution is disabled in Strategy Lab Beta. The app blocks Paper starts, exchange connections, and Hyperliquid testnet orders in both the UI and the backend.
• Bring your own AI access. Provider terms, model availability, and usage charges apply. Local storage does not mean remote AI requests stay on your device.
• Use a dedicated Agent/API Wallet in a future testnet release. Never provide a master-wallet private key. See configuration and credential handling.
• Backtests are evidence to inspect, not a promise. Paper and historical results do not predict future performance. Catbots is experimental trading software, not financial advice.

Build with us

Try a strategy, tell us where the workflow is unclear, or contribute a reusable node. Concrete examples and reproducible bug reports help make Catbots better.

Start here	What you will find
Contributing	Development setup and engineering boundaries
User guide	Configuration, AI providers, local web mode, and architecture
Community Node SDK	Manifest format, authoring, versioning, and limits
Security	How to report vulnerabilities privately
Brand guide	Cat-C artwork, colors, and language

For code changes, use Node.js 22 and run the relevant tests, then the full checks:

pnpm typecheck
pnpm test
pnpm test:e2e
git diff --check

The E2E suite packages Electron and manages native module rebuilding. Stop separate Electron development processes before running it.

To run the final acceptance test against an OpenAI-compatible or Anthropic-compatible endpoint, provide the values through the process environment. The test does not save the key or print it in its failure summary.

CATBOTS_PROVIDER_KIND=openai-compatible \
CATBOTS_PROVIDER_URL=https://provider.example/v1 \
CATBOTS_PROVIDER_API_KEY=your-key \
CATBOTS_PROVIDER_MODEL=provider/model \
pnpm test:provider

Source and license

Catbots is built in the open. An open-source license has not yet been selected, so reuse permissions are not granted automatically. See the source, try the workflow, and join the discussion as the project develops.

Curious by design. Clear by choice.