LocoAgent: an LLM agent that drives Chrome through CDP to operate social accounts

The problem LocoAgent targets: social actions that need a logged-in browser

Most social automation is written against platform APIs, and those APIs are the wrong shape for the job. A like, a follow, a reply and a post are all trivial in a browser and awkward or forbidden through an API. LocoAgent takes the opposite route. It drives a real Chrome instance over the Chrome DevTools Protocol, using the cookies already in that browser profile, so the agent acts as the account holder rather than as an application with a token. The README states this plainly: it drives Chrome via CDP with your actual login cookies, with no headless fingerprint.

The audience is narrow and specific. This is for engineers who want an agent to perform composite social tasks (find a post, read it, decide, reply) and who are willing to keep a browser session alive to do it. It is not a scheduling tool for marketing copy, and it is not a wrapper around the X or LinkedIn APIs. If your workflow is already served by an official API with a documented rate limit, LocoAgent adds a browser, a runtime and an LLM bill for no gain.

How the perceive, decide, act loop is wired

The architecture diagram in the README shows a single loop with three inputs feeding the system prompt. The agentic loop lives in query.ts, the system prompt in prompts.ts, and the two exchange messages. On one side the loop talks to an LLM provider through an Anthropic or OpenAI shim. On the other it calls tools, and the tool that matters is Bash, which shells out to the agent-browser CLI. That CLI talks to Chrome on CDP port 9222, and Chrome renders the live page.

Three things are injected into the prompt rather than passed as arguments: platform skills, the persona directory, and the operation log. Skills are operation playbooks, and the README gives a concrete number, 37 operations for X.com, loaded so the agent can finish a composite task in one pass instead of rediscovering the page each turn. The persona directory supplies the persona plus tasks. The operation log is a persistent deduplication store: the loop checks it before acting so a like, follow or reply is not repeated across sessions.

The verification step is the part worth noting. The README describes the cycle as perceive with agent-browser snapshot, decide with the LLM, act with click, fill or open, then verify the result before continuing. That ordering is what separates this from a script that fires a click and hopes. It also means every action costs at least one extra model round trip, which is a real cost at scale.

Installing LocoAgent and running a first task

The prerequisites are strict. Bun is required as both runtime and package manager, and the README says Node is not enough. Node.js 18 or later is still needed by some dependencies, along with the agent-browser CLI, current Google Chrome, and Git. The one-click installer handles Bun and agent-browser, clones the repository, scaffolds .env and runs the health check. On macOS, Linux or WSL2 it is a single curl piped to bash, and on Windows a PowerShell equivalent. It installs into the current directory, using an empty folder as-is and otherwise creating a ./locoagent subfolder, which LOCO_DIR overrides. Chrome and Git are detected, not installed, so the script will warn rather than fix.

For a manual setup, clone and install with Bun, then verify the environment before the first run:

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

The doctor script checks Bun, agent-browser, Chrome and your .env in one shot; adding --check-cdp also probes the CDP port. Configuration goes in a .env file at the project root, which is auto-loaded at startup through the preloaded stubs/globals.ts. Only the API key is strictly required. The four neutral variables are the front door:

# .env
LLM_PROVIDER=deepseek
LLM_API_KEY=
LLM_MODEL=deepseek-chat
LLM_BASE_URL=

LLM_PROVIDER accepts deepseek, openai, anthropic or custom. LLM_BASE_URL is only needed for custom or self-hosted OpenAI-compatible endpoints, for example http://localhost:1234/v1. The underlying OPENAI_* and ANTHROPIC_* variables still work and an explicitly set value there wins over the LLM_* block. Then start Chrome with the setup script and launch the REPL:

bun run setup-chrome && bun start

For a single non-interactive query, the README shows print mode with a model flag:

bun start -p "open X.com and like the first post about AI agents"
bun start --model anthropic/claude-sonnet-4.5

One caution before you run either: the example task likes a post on a live account. The repository also ships bun run run-tasks:dry, which is the safer first pass.

The fork decision: what reusing the Claude Code tree buys and costs

LocoAgent is a fork of the Claude Code CLI source tree. The README is candid about this: the agent loop, roughly 40 tools, roughly 90 slash commands and the Ink/React terminal UI are reused, with a thin LocoAgent layer for skills, workflows, persona and the operation log on top. That is a large amount of behaviour inherited for free, and it explains why the tool surface feels like a coding assistant rather than a social bot.

It also explains the package.json. The bin entry is still named claude-clean and points at src/entrypoints/cli.tsx. Several dependencies are file: references into a stubs directory, including @anthropic-ai/claude-agent-sdk, @ant/claude-for-chrome-mcp, @ant/computer-use-mcp and @anthropic-ai/sandbox-runtime. Those are local stubs, not published packages. Anyone expecting to consume LocoAgent as a library from npm will find that the published surface is not the point; this is an application you clone and run. The version field in package.json reads 1.1.0 while the latest release is v1.2.0, a small inconsistency that tells you the release tag and the manifest are maintained separately.

The trade-off is upgrade drag. Every improvement upstream in the Claude Code tree has to be merged into a fork that has renamed entrypoints and stubbed dependencies. The README does not describe how that merge happens, and no changelog entry explains it either.

Where the workflow engine ends and the agent begins

The README draws a line between two execution models. The agentic loop is LLM-driven and adaptive, which is what you want when the page is unpredictable. The workflow engine is described as deterministic, LLM-free browser pipelines that the agent supervises, started, stopped and scheduled as a daemon. The package.json exposes this as a set of scripts: workflow:list, workflow:status, workflow:summary, workflow:run and workflow:daemon.

That split is the most interesting design choice in the project. Anything you can express as a fixed sequence should not be paying for model tokens or risking a hallucinated click, and the workflow engine is the escape hatch. The agent then supervises rather than performs. In practice this means a mature deployment will run mostly workflows with the agent loop reserved for the parts that genuinely need judgement.

The README does not document the workflow file format, so how much of a given task you can actually express deterministically is unclear. The workflows/ directory at the repository root is where those definitions live, and reading it is the fastest way to answer that question before you commit to the split.

Multi-platform concurrency and its serialization rule

LocoAgent can drive X, LinkedIn and Reddit at the same time. The mechanism is one isolated Chrome instance per platform. The concurrency rule is stated precisely: same-platform operations are serial, cross-platform operations are parallel. Two tasks on X queue behind each other; a task on X and a task on LinkedIn do not.

That rule is a direct consequence of the browser-per-platform design, and it is the right default. Two agents clicking through the same X session would interleave snapshots and act on stale page state. Isolating by browser removes the shared mutable resource entirely. The cost is memory and process count: three platforms means three Chrome instances, each with its own profile and login state, plus whatever the operation log needs to keep them from duplicating each other's work.

Cross-platform deduplication is where this gets uncomfortable. The operation log prevents the agent from repeating a like or follow, but the README does not say whether that log is keyed per platform or globally. If you run the same persona across three networks, that distinction determines whether you get one action or three. The README is silent here, so test it on a throwaway account before trusting it.

What LocoAgent is not: platform terms, account risk and no rollback story

The README markets the absence of a headless fingerprint as a feature. Read it as a warning instead. Driving a real logged-in Chrome session means the platform sees exactly what a human session looks like, and automated operation of a social account is a terms-of-service question on every one of the three named platforms. LocoAgent does not answer that question, and no amount of CDP realism changes it. The account at risk is yours.

There is a second, more mundane gap. The README does not document rollback. If the agent likes the wrong post, follows the wrong account or publishes a draft, there is no described undo path and no described dry-run mode for a single live task. The repository does ship bun run run-tasks:dry, but the README does not explain what that dry run suppresses. Treat any live task as irreversible until you have verified otherwise.

The third limitation is runtime lock-in. Bun is not a preference here, it is a requirement, and the preload of stubs/globals.ts is part of how .env reaches the process. If your infrastructure standardises on Node, adopting LocoAgent means adding a second runtime to your stack. That is a real cost, and it is not negotiable through configuration.

LocoAgent against Playwright and Puppeteer

The honest alternative is not another social agent. It is a Playwright or Puppeteer script that logs into the same platforms and performs the same actions. Both drive Chrome through CDP, so the browser-level capability is comparable.

The difference is where the decision lives. In a Playwright script you write the selector, the click and the retry logic, and the script does exactly that until the page changes and it breaks. LocoAgent puts an LLM between the page and the action. It snapshots the page, asks a model what to do next, and adapts when the layout shifts. In exchange you accept non-determinism, token cost per action, and a failure mode where the model picks a plausible but wrong element. The operation log and the workflow engine are the project's answer to that trade-off: keep the adaptive loop for the unpredictable part, and push everything else into deterministic pipelines.

If your target pages are stable and your action list is short, Playwright wins on cost, predictability and debuggability, and you should not adopt LocoAgent. If the pages change often and the task requires reading content to decide what to do, the agentic loop is doing work that a selector-based script cannot.

Editorial conclusion

Adopt LocoAgent if you already run Chrome with the accounts you intend to automate, you are comfortable with Bun as the only supported runtime, and you want an auditable operation log rather than a hand-written Playwright script. Do not adopt it if you need a hosted service, a stable public API, or a documented rollback path, because the README does not describe one. Before committing, run bun run doctor --check-cdp and confirm the CDP endpoint on port 9222 answers, then run bun run run-tasks:dry so the first task pass executes without touching a live account.

Frequently asked questions

Official sources

1. License: MIT
2. LocoreMind/locoagent on GitHub
3. Project website
4. README
5. Releases