@locoremind/locoagent

{ "name": "locoagent", "version": "1.1.0", "description": "LocoAgent - AI-powered social media agent by LocoreMind", "type": "module", "bin": { "claude-clean": "./src/entrypoints/cli.tsx" }, "scripts": { "start": "bun run --preload ./stubs/globals.ts ./src/entrypoints/cli.tsx", "setup-chrome": "bun run scripts/setup-chrome.ts", "setup-chrome:win": "bun run scripts/setup-chrome.ts", "doctor": "bun run scripts/doctor.ts", "run-tasks": "bun run scripts/run-tasks.ts", "run-tasks:dry": "bun run scripts/run-tasks.ts --dry-run", "tail": "bun run scripts/tail-agent.ts", "tail:history": "bun run scripts/tail-agent.ts --from-start", "tail:list": "bun run scripts/tail-agent.ts --list", "workflow": "bun run scripts/workflow-engine.ts", "workflow:list": "bun run scripts/workflow-engine.ts list", "workflow:status": "bun run scripts/workflow-engine.ts status", "workflow:summary": "bun run scripts/workflow-engine.ts summary", "workflow:run": "bun run scripts/workflow-engine.ts run", "workflow:daemon": "bun run scripts/workflow-engine.ts daemon", "typecheck": "tsc --noEmit", "test": "bun test scripts" }, "dependencies": { "@alcalzone/ansi-tokenize": "^0.1.0", "@ant/claude-for-chrome-mcp": "file:./stubs/@ant/claude-for-chrome-mcp", "@ant/computer-use-mcp": "file:./stubs/@ant/computer-use-mcp", "@ant/computer-use-swift": "file:./stubs/@ant/computer-use-swift", "@ant/computer-use-input": "file:./stubs/@ant/computer-use-input", "@anthropic-ai/claude-agent-sdk": "file:./stubs/@anthropic-ai/claude-agent-sdk", "@anthropic-ai/mcpb": "file:./stubs/@anthropic-ai/mcpb", "@anthropic-ai/sandbox-runtime": "file:./stubs/@anthropic-ai/sandbox-runtime", "@anthropic-ai/sdk": "^0.39.0", "@aws-sdk/client-bedrock-runtime": "^3.700.0", "commander": "~13.1.0", "@commander-js/extra-typings": "^13.0.0", "@growthbook/growthbook": "^1.3.0", "@modelcontextprotocol/sdk": "^1.12.0", "@opentelemetry/api": "^1.9.0", "@opentelemetry/api-logs": "^0.200.0", "@opentelemetry/core": "^2.0.0", "@opentelemetry/resources": "^2.0.0", "@opentelemetry/sdk-logs": "^0.200.0", "@opentelemetry/sdk-metrics": "^2.0.0", "@opentelemetry/sdk-trace-base": "^2.0.0", "@opentelemetry/semantic-conventions": "^1.30.0", "ajv": "^8.17.0", "asciichart": "^1.5.0", "auto-bind": "^5.0.0", "axios": "^1.7.0", "bidi-js": "^1.0.0", "chalk": "^5.4.0", "chokidar": "^4.0.0", "cli-boxes": "^3.0.0", "code-excerpt": "^4.0.0", "diff": "^7.0.0", "emoji-regex": "^10.4.0", "env-paths": "^3.0.0", "execa": "^9.5.0", "figures": "^6.1.0", "fuse.js": "^7.0.0", "get-east-asian-width": "^1.3.0", "google-auth-library": "^9.15.0", "highlight.js": "^11.11.0", "https-proxy-agent": "^7.0.0", "ignore": "^7.0.0", "indent-string": "^5.0.0", "ink": "^5.1.0", "jsonc-parser": "^3.3.0", "lodash-es": "^4.17.0", "lru-cache": "^11.0.0", "marked": "^15.0.0", "p-map": "^7.0.0", "picomatch": "^4.0.0", "proper-lockfile": "^4.1.0", "qrcode": "^1.5.0", "react": "^19.0.0", "react-reconciler": "^0.33.0", "semver": "^7.7.0", "shell-quote": "^1.8.0", "signal-exit": "^4.1.0", "stack-utils": "^2.0.0", "strip-ansi": "^7.1.0", "supports-hyperlinks": "^3.1.0", "tree-kill": "^1.2.0", "type-fest": "^4.32.0", "undici": "^7.4.0", "usehooks-ts": "^3.1.0", "vscode-jsonrpc": "^8.2.0", "vscode-languageserver-protocol": "^3.17.0", "vscode-languageserver-types": "^3.17.0", "wrap-ansi": "^9.0.0", "ws": "^8.18.0", "xss": "^1.0.0", "zod": "^3.25.0" }, "devDependencies": { "@types/bun": "latest", "@types/react": "^19.0.0", "@types/lodash-es": "^4.17.0", "@types/semver": "^7.5.0", "@types/ws": "^8.5.0", "@types/diff": "^7.0.0", "@types/shell-quote": "^1.7.0", "@types/proper-lockfile": "^4.1.0", "@types/qrcode": "^1.5.0", "typescript": "^5.7.0" }, "overrides": { "@ant/claude-for-chrome-mcp": "file:./stubs/@ant/claude-for-chrome-mcp", "@ant/computer-use-mcp": "file:./stubs/@ant/computer-use-mcp", "@ant/computer-use-swift": "file:./stubs/@ant/computer-use-swift", "@ant/computer-use-input": "file:./stubs/@ant/computer-use-input", "@anthropic-ai/mcpb": "file:./stubs/@anthropic-ai/mcpb", "@anthropic-ai/sandbox-runtime": "file:./stubs/@anthropic-ai/sandbox-runtime", "@anthropic-ai/claude-agent-sdk": "file:./stubs/@anthropic-ai/claude-agent-sdk", } }

📑 Table of Contents

• ✨ What is LocoAgent?
• 🏗️ How It Works
• 🚀 Installation
• ⚙️ Configuration
• 🧠 Model Providers
• 🌐 Browser Automation
• 🎯 Platform Skills
• 🌍 Multi-Platform Targets
• 🔁 Workflow Engine
• 📒 Operation Log
• 🗓️ Task Scheduling
• 📡 Trajectory Monitor
• 🩺 Doctor — Health Check
• 📁 Project Structure
• 🧩 Tech Stack
• 🤝 Contributing
• 📄 License

✨ What is LocoAgent?

LocoAgent is an AI-powered social-media agent that autonomously operates real accounts through genuine browser automation. It pairs an LLM-driven agentic loop with the agent-browser CLI to perceive → decide → act on live web pages — liking posts, writing replies, following users, and publishing content the way a human would.

Under the hood it is a fork of the Claude Code CLI source tree, re-purposed for social automation: the battle-tested agent loop, ~40 tools, ~90 slash commands, and Ink/React terminal UI are reused, with a thin LocoAgent-specific layer (skills, workflows, persona, operation log) layered on top.

🌟 Why LocoAgent?

🏗️ How It Works

flowchart LR
    User([👤 User / Task]) --> Loop

    subgraph Agent["🤖 LocoAgent Core"]
        Loop["Agentic Loop<br/>(query.ts)"]
        Prompt["System Prompt<br/>(prompts.ts)"]
        Loop <--> Prompt
    end

    Loop <-->|"Anthropic / OpenAI shim"| LLM["🧠 LLM Provider"]
    Loop --> Tools["🛠️ Tools · Bash"]
    Tools --> AB["🌐 agent-browser CLI"]
    AB --> CDP["Chrome CDP :9222"]
    CDP --> Web[("🌍 Live Web Page")]

    Skills["🎯 Platform Skills"] -. inject playbook .-> Prompt
    Persona["🪪 persona/"] -. persona + tasks .-> Prompt
    OpLog[("📒 Operation Log")] -. dedup .-> Prompt

    WF["🔁 Workflow Engine"] --> AB

The agent perceives a page with agent-browser snapshot, the LLM decides the next action, a tool acts (click, fill, open), and the result is verified before the loop continues — checking the operation log first so nothing gets done twice.

🚀 Installation

✅ Prerequisites

⚡ One-click install (recommended)

One command installs Bun + agent-browser, clones the repo, scaffolds .env, and runs the health check. When run in a terminal it asks you to pick a provider (DeepSeek / Anthropic / OpenAI), enter your API key, then pick a model (Enter takes the latest; c lets you type any model name). The base URL is fixed per provider — no need to type it.

macOS / Linux / WSL2

curl -fsSL https://raw.githubusercontent.com/LocoreMind/locoagent/main/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/LocoreMind/locoagent/main/install.ps1 | iex

Installs into the current directory (an empty folder is used as-is; otherwise a ./locoagent subfolder is created; override with LOCO_DIR). The installer prints the exact target and lets you confirm it. Re-running from inside the checkout updates it in place. Afterwards: bun run setup-chrome && bun start. Chrome and Git are detected (not auto-installed) — install them if the script warns.

📥 Manual setup

git clone https://github.com/LocoreMind/locoagent.git
cd locoagent
bun install

# Verify your environment before first run
bun run doctor

▶️ Run

# Interactive REPL
bun start

# Single query (headless / print mode)
bun start -p "open X.com and like the first post about AI agents"

# With a specific model
bun start --model anthropic/claude-sonnet-4.5

[!TIP] bun run doctor checks Bun, agent-browser, Chrome, and your .env in one shot. Add --check-cdp to probe the CDP port too.

⚙️ Configuration

Create a .env file in the project root — it is auto-loaded at startup (via the preloaded stubs/globals.ts). Configure your provider through the four neutral LLM_* variables; they are translated to the right internal settings at startup, so you never juggle provider-specific variable names:

# ── LLM Provider — pick ONE ──────────────────────────────
LLM_PROVIDER=deepseek        # deepseek | openai | anthropic | custom
LLM_API_KEY=sk-...
LLM_MODEL=deepseek-chat      # blank = provider default
LLM_BASE_URL=                # only for `custom` / self-hosted OpenAI-compatible APIs

# Examples:
#   OpenAI    → LLM_PROVIDER=openai     LLM_MODEL=gpt-5.5
#   Anthropic → LLM_PROVIDER=anthropic  LLM_MODEL=claude-sonnet-4-6
#   Custom    → LLM_PROVIDER=custom     LLM_BASE_URL=http://localhost:1234/v1  LLM_MODEL=...

# ── Agent behavior ───────────────────────────────────────
SKIP_PERMISSIONS=1                             # required for non-interactive / automated runs

[!TIP] The LLM_* block is the recommended front door. Under the hood it maps to the legacy CLAUDE_CODE_USE_OPENAI / OPENAI_* / ANTHROPIC_* variables, which still work directly for existing setups — an explicitly-set legacy value always wins. DeepSeek, OpenAI, OpenRouter, and every OpenAI-compatible endpoint share the same OPENAI_* namespace internally; the provider is decided by the base URL + model, not by the variable name.

[!NOTE] SKIP_PERMISSIONS=1 makes stubs/globals.ts inject --dangerously-skip-permissions into argv so automated/headless runs don't stop on permission prompts.

🧠 Model Providers

LocoAgent talks to any OpenAI-compatible API through a built-in translation shim (src/services/api/openaiShim.ts), keeping the rest of the system provider-agnostic.

Pick any of these with LLM_PROVIDER + LLM_BASE_URL (e.g. LLM_PROVIDER=custom, LLM_BASE_URL=https://openrouter.ai/api/v1). The neutral front door maps to the shim automatically; advanced users can still set CLAUDE_CODE_USE_OPENAI=1 and the OPENAI_* vars directly.

Behind a TLS-intercepting proxy (corporate VPN / campus FortiGate / Zscaler)

If a request fails with unable to get local issuer certificate or untrusted root, your network is re-signing TLS with its own CA. Export that gateway's root certificate to a .pem file and point NODE_EXTRA_CA_CERTS at it in .env — LocoAgent then trusts it on every provider path, including the DeepSeek/OpenAI shim. If the provider host is outright blocked on that network, switch networks (e.g. a phone hotspot) or pick a provider that is allowed.

🌐 Browser Automation

LocoAgent controls a real Chrome browser over CDP (Chrome DevTools Protocol) using agent-browser.

🔒 Why Chrome CDP?

Social platforms detect and block headless browsers and API automation. LocoAgent runs through a real, full Chrome — same engine, same fingerprint — so it behaves like you actually do. It uses a dedicated, isolated, persistent profile (separate from your everyday Chrome): you log into your accounts once and the session sticks, while your normal browsing is never disturbed.

🛠️ Setup

# One-time: launch the isolated Chrome with CDP (same command on Windows / macOS / Linux).
# It never kills your normal Chrome and never wipes your session.
bun run setup-chrome

# First run only: log into X / your socials in the window that opens — it persists.
# Re-running just reconnects. To wipe the isolated profile and log in fresh:
bun run setup-chrome --reset

# Multi-platform: launch one target, or every target at once (one Chrome each).
bun run setup-chrome --target linkedin
bun run setup-chrome --all

👀 The Perceive → Act → Verify Loop

agent-browser open https://x.com/home     # 🧭 Navigate
agent-browser snapshot -i                  # 👀 Perceive — interactive elements with @ref IDs
agent-browser click @e5                     # 👆 Act — click a like button
agent-browser fill @e3 "Great research!"   # ⌨️  Act — type into a reply box
agent-browser screenshot result.png        # ✅ Verify — capture the result

The full agent-browser CLI reference is embedded in the agent's system prompt, so it knows every command natively — skills and workflows reference operations by name rather than re-explaining them.

🎯 Platform Skills

Skills are operation playbooks loaded on demand via slash commands. Loading one injects a complete manual into the agent's context, enabling composite task execution in a single pass.

📚 Available Skills

💬 Usage

# Interactive — load the skill, then give a task
> /x-com open home timeline, like first 3 posts about AI, reply to the best one

# Headless
bun start -p "/x-com like 5 posts about 'large language models', then follow the authors"

➕ Adding a New Platform

Create skills/<platform>/SKILL.md with YAML frontmatter:

---
description: "LinkedIn platform operations playbook"
allowed-tools:
  - Bash
user-invocable: true
---

# LinkedIn Operations

## 1. Navigation
...
## 2. Engagement
...

The skill auto-discovers at startup and becomes available as /linkedin. Design each operation as a self-contained section with preconditions, agent-browser commands, a verification step, and known pitfalls (see skills/x-com/SKILL.md for the established format).

🌍 Multi-Platform Targets

Run several social platforms at the same time — each in its own isolated Chrome, on its own CDP port, behind its own proxy. A single registry, config/browser-targets.json, is the source of truth:

{
  "targets": {
    "x":        { "cdpPort": 9222, "proxy": "http://127.0.0.1:6738" },
    "linkedin": { "cdpPort": 9223, "proxy": null },
    "reddit":   { "cdpPort": 9224, "proxy": null }
  }
}

setup-chrome --all/--target, the workflow engine, and doctor --check-cdp all read from it — add a platform once and every tool picks it up.

bun run setup-chrome --all            # 🚀 one isolated Chrome per platform
bun run doctor --check-cdp            # 🩺 probe every target's CDP port

🔀 Same-platform serial · cross-platform parallel

The engine reads each workflow's "platform" field and injects the matching target (cdpPort, profile, proxy, device) into the executor — you never hard-code a port. A per-platform file lock then keeps same-platform runs serial (one active tab per profile) while different platforms run concurrently:

# x + x → serialized; linkedin → in parallel with them. Automatically.
bun run workflow orchestrate --ids hf-papers-to-x,x-search-reply,linkedin-search-reply

🔁 Workflow Engine

Workflows are deterministic browser-automation pipelines that run without any LLM in the control flow (an LLM may still be called as a single step). The agent acts as a supervisor — it can inspect status and start/stop runs, while execution stays scripted and reproducible.

📦 Built-in Workflows

🖥️ CLI

bun run workflow list                          # 📋 List all workflows + status
bun run workflow run    --id hf-papers-to-x    # ▶️  Run once (blocking)
bun run workflow start  --id hf-papers-to-x    # 🚀 Run once (background)
bun run workflow daemon --id x-search-reply --interval 3   # 🔄 Run every 3 minutes
bun run workflow orchestrate --ids a,b,c       # 🌍 Multi-platform: same serial, cross parallel
bun run workflow stop   --id x-search-reply    # 🛑 Stop at next checkpoint
bun run workflow reset  --id x-search-reply    # ♻️  Clear stopped state → idle
bun run workflow status                        # 📊 Status of all workflows
bun run workflow history --id hf-papers-to-x   # 🕘 Execution history

🧱 Creating a Custom Workflow

Step 1 — Definition (workflows/<id>.json):

{
  "id": "my-workflow",
  "name": "My Custom Workflow",
  "description": "What this workflow does",
  "schedule": "daily",
  "platform": "x",
  "executor": "executors/my-workflow.ts",
  "config": { "searchQuery": "ai agent", "maxPosts": 5 }
}

[!TIP] Set "platform" (e.g. x / linkedin / reddit) — never hard-code cdpPort. The engine injects the target's cdpPort, profile, proxy, and device from config/browser-targets.json into config at run time, and locks the platform for the run.

Step 2 — Executor (workflows/executors/my-workflow.ts):

#!/usr/bin/env bun
import { execSync } from 'node:child_process'

const configArg = process.argv.find((_, i, a) => a[i - 1] === '--config')
const config = JSON.parse(configArg!)

function ab(cmd: string): string {
  return execSync(`agent-browser --cdp ${config.cdpPort} ${cmd}`, {
    encoding: 'utf-8', timeout: 30000,
  }).trim()
}

console.error('[my-workflow] Step 1: ...')        // 📝 logs → stderr
// ... your automation logic using ab() ...

console.log(JSON.stringify({ stepsCompleted: 1, stepsTotal: 1 }))   // 📤 summary → last line of stdout

Step 3 — Test:

bun run workflow run --id my-workflow

[!IMPORTANT] Executor contract: accept --config <json>, log to stderr, and emit a single JSON object ({stepsCompleted, stepsTotal}) as the last line of stdout. Missing or malformed output marks the run as failed.

📖 Full guide: docs/workflow-development-guide.md — covers deduplication, the checkpoint/stop protocol, LLM integration, and daemon mode.

📒 Operation Log

Persistent memory across sessions. The agent checks the log before acting and records every action after — preventing duplicate likes, follows, and replies. This dedup contract is the core of the agent's identity.

# 🔍 Check before acting (exit 0 = already done → skip; exit 1 = not done → proceed)
bun run scripts/log-operation.ts check \
  --platform x --action like --url "https://x.com/.../status/123"

# ✅ Record after a successful action
bun run scripts/log-operation.ts add \
  --platform x --action like --url "https://x.com/.../status/123" \
  --status success --note "AI agents research post"

# 🕘 View recent operations
bun run scripts/log-operation.ts recent --limit 20

# 📊 30-day summary (auto-injected into the system prompt at startup)
bun run scripts/log-operation.ts summary --days 30

State lives in persona/operation-log.json (human-readable JSON). The 30-day summary is injected into every session's system prompt so the agent always knows its recent history.

🗓️ Task Scheduling

Replace ad-hoc prompts with structured daily/weekly task execution.

📝 Define Tasks — persona/tasks.md

## Daily Tasks
1. Engage with relevant content (like posts matching topic queries)
2. Monitor own project mentions
3. Leave 1 technical comment on the most relevant post

## Weekly Tasks (Monday)
4. Follow 3-5 relevant researchers
5. Post 1 original tweet about recent research findings

## Session Constraints
| Action   | Max per session |
|----------|:---------------:|
| Likes    | 10              |
| Comments | 2               |
| Follows  | 5               |
| Posts    | 1               |

▶️ Run

bun run run-tasks                   # Execute today's tasks
bun run run-tasks:dry               # Preview the generated prompt without running
bun run run-tasks -- --platform x   # Restrict to one platform

[!NOTE] persona/ is gitignored and absent from a fresh clone. The agent runs fine without it — just without persona, task, and operation-history context in the prompt.

📡 Trajectory Monitor

--print mode is a black box. The trajectory monitor watches the session log and prints live execution status.

# Terminal 1 — start the monitor
bun run tail

# Terminal 2 — run the agent
bun start -p "/x-com open timeline, like first post"

═══ New Task ═══
/x-com open timeline, like first post

[6:30:47 PM] ⚡ Bash: agent-browser connect 9222
[6:30:47 PM] ✓ Result: Done
[6:31:10 PM] ⚡ Bash: agent-browser open https://x.com/home
[6:31:27 PM] ⚡ Bash: agent-browser snapshot -i -c -s 'article'
[6:31:44 PM] ● Agent: Found first post, like button ref=e136
[6:31:44 PM] ⚡ Bash: agent-browser click e136
[6:31:45 PM] ✓ Result: Done

bun run tail:history     # 🔁 Replay latest session from the beginning
bun run tail:list        # 📋 List recent sessions
bun run tail <id>        # 🎯 Watch a specific session

🩺 Doctor — Health Check

A cross-platform preflight check and onboarding aid. Run it before your first session or whenever something feels off.

bun run doctor               # Check Bun, agent-browser, Chrome, .env
bun run doctor --check-cdp   # …also probe every platform target's CDP port

It detects your host OS (Windows / macOS / Linux), resolves the Chrome binary path, probes each target in config/browser-targets.json, and reports anything missing or misconfigured.

📁 Project Structure

locoagent/
├── src/                          # ⬆️ Vendored Claude Code CLI source — treat as a dependency
│   ├── entrypoints/cli.tsx       #    CLI entry point
│   ├── services/api/             #    Multi-provider LLM shim (openaiShim / codexShim)
│   ├── services/mcp/             #    MCP server management
│   ├── tools/                    #    ~40 tool implementations
│   ├── commands/                 #    ~90 slash commands
│   ├── components/ · hooks/      #    Ink/React terminal UI
│   ├── query.ts                  #    Agentic loop engine
│   └── constants/prompts.ts      #    🔌 The seam — injects LocoAgent state into the prompt
├── scripts/                      # 🧩 LocoAgent-specific tooling
│   ├── setup-chrome.ts           #    Chrome + CDP launcher (cross-platform)
│   ├── doctor.ts                 #    Health check / onboarding
│   ├── log-operation.ts          #    Operation-log CLI (dedup)
│   ├── run-tasks.ts              #    Task scheduler
│   ├── tail-agent.ts             #    Live trajectory monitor
│   ├── workflow-engine.ts        #    Workflow lifecycle manager
│   └── lib/                      #    Platform layer — host · device · config · target lock
├── config/
│   └── browser-targets.json      # 🌍 Per-platform target registry (cdpPort · proxy · profile)
├── skills/<platform>/SKILL.md    # 🎯 Platform operation playbooks (→ /<platform>)
├── workflows/
│   ├── <id>.json                 #    Workflow definitions
│   ├── executors/<id>.ts         #    Scripted pipelines
│   └── state.json                #    Runtime state (gitignored)
├── persona/                      # 🪪 Persona, tasks, operation log (gitignored)
├── docs/                         # 📖 Public docs (workflow guide, cross-platform guide)
├── stubs/                        #    Preloaded globals + local package stubs
├── .env                          #    Local config (auto-loaded)
└── package.json

[!TIP] The LocoAgent layer is small and lives outside src/. The seam is src/constants/prompts.ts, which shells out to inject persona, tasks, operation-log summary, and workflow status into every session's system prompt.

🧩 Tech Stack

🤝 Contributing

Contributions welcome! High-impact areas:

• 🎯 New platform skills — LinkedIn, Reddit, Instagram playbooks
• 🔁 New workflows — automated content pipelines (development guide)
• 🛠️ New tools — extend agent capabilities
• 🐛 Bug fixes — especially browser-automation edge cases

Branch → change → bun run typecheck → commit (feat: / fix: / docs:) → PR with What / Why / How / Testing. See CONTRIBUTING.md for the full guide.

[!NOTE] There is no unit-test suite. Verify with bun run typecheck and a real bun start -p "..." run. bun test scripts runs the platform-layer unit tests.

📄 License

MIT © LocoreMind