ilo

Local X research and publishing for people and AI agents. Search public audiences, monitor replies and articles, draft from evidence, and publish after review.

Get started · Documentation · Publishing accounts · Audience research · Following search · Article monitoring · npm · Questions · Privacy · Security · License · Agent notes

ilo gives your agent public X evidence it can inspect before it tells you what
to publish. Search follower profiles and the people an account follows, keep
native X Articles in a local full-text index, collect focused replies, and turn
the useful findings into drafts.

The CLI, local MCP server, agent skill, and TypeScript package call the same
core implementation. Drafts, monitor state, article text, schedules, and
publish attempts stay in your local SQLite database. Publishing always stops
for explicit confirmation.

Who this is for

People growing an X account who want research, reply triage, drafts, and
publishing in one local workflow.
Coding agents get inspectable public evidence through MCP instead of working
from screenshots or generic social media advice.
Consultants, social teams, and developers can research public accounts or
embed the same typed functions in their own tools.

Quick start

ilo requires Node 22.19 or newer.

npm i -g iloso
ilo start

ilo start asks whether you want to publish through Typefully or directly
through your own X developer app.

For Typefully, create a v2 API key under Settings → API and paste it into
the hidden prompt. ilo adds every accessible Typefully social set with an X
profile.

For direct X, create a Native App with OAuth 2.0 read and write access, then
register this callback exactly:

http://127.0.0.1:8976/callback

Copy the OAuth 2.0 Client ID from the app's Keys and tokens page. Native
Apps use PKCE and do not need a client secret. ilo opens the browser sign-in.
Typefully API keys and X OAuth tokens stay in your operating system keychain.

List or switch between every connected X publishing account:

ilo accounts list
ilo accounts use <alias-or-handle>

Run ilo --help to see the main surface:

Local-first social publishing for people and AI agents

USAGE ilo start|accounts|x|post|drafts|scheduler|mcp|skill

COMMANDS
      start    Connect Typefully or your own X developer app
   accounts    Connect and switch between X publishing accounts
          x    Research and manage X accounts
       post    Publish one post or reply to X
     drafts    Create, list, schedule, and publish local drafts
  scheduler    Run scheduled local drafts
        mcp    Run the local stdio MCP server
      skill    Inspect or install the packaged ilo agent skill

The default publishing account's handle becomes the local namespace for
article and inbox monitors. Research commands fetch public X data and keep the
results local.
Public follower research can run with no publishing connection. Commands that
need a research namespace also accept an explicit handle.

The publishing accounts guide explains
Typefully, direct X, multiple profiles, account aliases, and why drafts stay
bound to their original account.

What you can do

Search imported follower names, handles, bios, and locations with SQLite
FTS5, including evidence-backed current, former, and unclear employer
counts.
Search the complete public profiles an account follows, with snapshot
coverage, 24-hour freshness, JSON, CSV, and complete stored profile lookup.
Native X Articles from selected writers become a local full-text library
that the CLI or an agent can search later.
Focused X searches feed a deduplicated reply inbox with public post, author,
engagement, and relationship evidence.
Draft top-level posts or replies with up to four JPEG, PNG, or WebP images
and optional alt text.
Schedules accept exact timestamps or phrases such as tomorrow at 9am.
MCP and TypeScript callers use the same local data and confirmation rules as
the terminal.

Research public followers

Import a bounded sample, continue a full resumable sync, or let a large import
run as a detached local process:

ilo x followers sync adamwathan --pages 20
ilo x followers sync adamwathan --all
ilo x followers sync adamwathan --background
ilo x followers status adamwathan

Search the saved profiles once the index has data:

ilo x followers search adamwathan \
  --query "works at cursor|vercel|sentry"

Current matches are listed by default. Counts still show current, former, and
unclear classifications, and every listed profile includes the public bio
used as evidence. Add the noisier groups only when you need to inspect them:

ilo x followers search adamwathan \
  --query "works at cursor|vercel|sentry" \
  --include-former \
  --include-unclear

Search returns every selected match unless you pass --limit. Export the same
profiles and import coverage to CSV with --csv ./matches.csv. Check the
coverage first because an unfinished public import cannot support a complete
count.

The audience research guide covers
background progress, complete profile records, classification limits, local
MCP tools, TypeScript functions, terminal output, and CSV fields.

Search the people an account follows

Build a fresh local snapshot of your own following list, or name another
public account explicitly:

ilo x following sync --all
ilo x following sync adamwathan --all
ilo x following status adamwathan

An omitted handle uses the default publishing account's X handle as the local
research namespace. A bounded sync
reads 20 pages by default and resumes when you run it again. --all continues until the
available list ends, or until the saved profiles match X's
reported total and repeated pages add nothing new. Running sync after a
completed import starts a fresh snapshot, while --restart discards an
unfinished cursor.

Search the saved names, handles, bios, locations, and handle aliases locally:

ilo x following search adamwathan \
  --query "building browser tools"

Search uses SQLite FTS5, so concrete profile words work better than abstract
semantic questions. It returns every match unless you pass --limit. Each
result includes the public bio or location evidence, and the coverage says how
many complete profiles are searchable, whether the import finished, and
whether the snapshot is more than 24 hours old.

Export every match or inspect one complete stored profile:

ilo x following search adamwathan \
  --query "building browser tools" \
  --csv ./browser-builders.csv

ilo x following profile browser_builder \
  --account adamwathan \
  --json

The following search guide documents
sync and refresh behaviour, every CLI command, MCP tool, TypeScript function,
JSON field, CSV column, freshness rule, and current evidence limits.

Keep native X Articles searchable

Choose the writers worth keeping, refresh their public article timelines, and
search the saved full text:

ilo x articles add swyx
ilo x articles add karpathy
ilo x articles refresh
ilo x articles search --query "browser tools"
ilo x articles show <post-id-or-status-url>

ilo fetches the complete public body for each new native X Article and stores
the timeline cursor locally. If older history remains, the next refresh
continues from that cursor. Search has no hidden result limit and makes no
network request after the articles are saved.

This monitors native X Articles. It does not collect every external link or
normal post a handle shares. Search uses SQLite FTS5 rather than embeddings,
so concrete names and words work better than abstract semantic questions.

The article monitoring guide documents every
CLI command, MCP tool, TypeScript function, JSON field, history state, and
current limit.

Build a local reply inbox

Save focused X searches and refresh them when you want new posts:

ilo x monitors add "ilo mentions" \
  --query '"ilo" OR "ilo.so" -is:retweet'
ilo x inbox refresh
ilo x inbox list --verified

Import follower and following profiles when relationship filters matter:

ilo x following sync --all
ilo x followers sync <your-handle> --all
ilo x inbox list --i-follow
ilo x inbox list --follows-me

Relationship values stay unknown until the relevant local import has enough
coverage to answer. ilo does not turn missing data into false.
The following import is also the searchable profile index described in the
following search guide.

Inspect a post before drafting a reply:

ilo x inbox show <post-id-or-status-url>
ilo x inbox draft <post-id-or-status-url> --text "Reply to review"

Drafting saves the reply target and marks the inbox item as read. Nothing is
published until the normal confirmation step.

Draft, schedule, and publish

Publish one reviewed post directly:

ilo post --text "Hello from ilo"
ilo post \
  --reply-to https://x.com/example/status/123 \
  --text "A reply from ilo"
ilo post \
  --text "Weekly signups" \
  --image ./chart.png \
  --alt "Bar chart of weekly signups by source"

Save an idea when it is not ready yet:

ilo drafts create --text "Post this tomorrow"
ilo drafts list
ilo drafts schedule <draft-id> --at "tomorrow at 9am"
ilo drafts publish <draft-id>

Run due schedules once or keep a local watcher open:

ilo scheduler run
ilo scheduler watch --interval 60

Interactive publishing shows the exact text, top-level or reply destination,
and images before asking for confirmation. Use --yes only after another
caller has already confirmed that exact action.

Use ilo with AI agents

Install the packaged skill so a coding agent knows the workflow and publishing
rules:

ilo skill install

Add the local stdio MCP server to Claude Code or Codex:

claude mcp add ilo -- iloso mcp serve
codex mcp add ilo -- iloso mcp serve

Config-based clients can use the same command:

{
  "mcpServers": {
    "ilo": {
      "command": "iloso",
      "args": ["mcp", "serve"]
    }
  }
}

The client starts the server as a child process when it needs a tool. The
server uses stdin and stdout, opens no network port, and reads the same local
database as the CLI.

Keep research and publication as separate agent steps:

Search my saved X articles for browser tools. Show the strongest evidence and
any missing history. Do not draft or publish anything.

Create a local reply draft for this inbox item. Show me the exact text and
reply target, then stop for review.

Publishing tools require confirm: true for the exact action. Creating a
draft, searching local data, or refreshing a public monitor never publishes.

The local MCP guide lists the tools and setup for
Claude, Codex, Cursor, and other compatible clients.

Use ilo as a TypeScript package

Install iloso in a Node 22.19 or newer project:

npm install iloso

Call the same core functions used by the CLI and MCP server:

import {
  createDraft,
  createXArticleMonitor,
  getXArticle,
  refreshXArticleMonitor,
  scheduleDraft,
  searchXArticles,
} from 'iloso'

const monitor = createXArticleMonitor({
  accountHandle: 'ilodotso',
  sourceHandle: 'swyx',
})

await refreshXArticleMonitor({ id: monitor.id, maxPages: 3 })

const matches = searchXArticles({
  accountHandle: 'ilodotso',
  query: 'browser tools',
})

if (matches[0]) {
  const article = getXArticle({
    accountHandle: 'ilodotso',
    identifier: matches[0].postId,
  })

  const draft = await createDraft(`A useful idea from ${article.title}`)
  await scheduleDraft(draft.id, 'tomorrow at 9am')
}

The root package exports follower and following sync and search functions,
complete stored profile lookup, article monitoring, reply inbox actions,
publishing accounts, Typefully setup, local drafts, schedules, static image
helpers, X OAuth, public X helpers, configuration, and storage paths. The
package is pre-1.0, so pin the version when another application depends on
exact function signatures.

The TypeScript guide has complete examples
for research, drafting, publishing, and embedding the MCP server.

Know where the data goes

ilo keeps non-secret configuration under ~/.config/ilo and local working
data in ~/.config/ilo/ilo.sqlite. Typefully API keys, X OAuth tokens, and the
optional X client secret use your operating system keychain.

There is no hosted ilo account or draft database. The CLI makes the network
requests required to connect X, publish approved posts, and retrieve the
public research data you request. Set ILO_HOME when a script or test needs an
isolated local directory.

Back up ilo.sqlite if your drafts, monitor history, or saved research matter.
Do not copy keychain exports or OAuth tokens into a repository, issue, or shell
script.

Understand the current limits

X is the only publishing network today. It can publish through Typefully or
direct X OAuth. Bluesky and LinkedIn publishing are planned.
Typefully is a publishing route in the current release. Research works
independently of the publishing connection, and Typefully analytics
ingestion is planned for later.
Article monitors only collect native X Articles and refresh on demand.
Follower employer results classify claims in public bios. They do not verify
someone's employment.
The public report library explains useful performance analyses, but automated
local account-history reports have not shipped yet.
Images can be JPEG, PNG, or WebP. Animated GIF and video uploads are still
planned.

Public data can be incomplete, delayed, or unavailable. ilo keeps coverage and
fetch errors visible so an agent can describe what the result supports.

Common questions

Do I need an X developer app?

No. Connect a personal Typefully v2 API key when your X profiles already live
there. Direct publishing through X still needs your own X Native App. Public
follower research does not require either connection. Article and inbox
commands can use an explicit handle as their local namespace.

Can I use several X accounts?

Yes. ilo accounts add typefully imports every accessible X social set, and
ilo accounts add x connects another direct X profile. Use ilo accounts use
to change the default or pass --account for one action. Existing drafts stay
on the account they were created for.

Will ilo post without asking me?

No. Interactive commands ask for confirmation, and MCP publishing tools
require confirm: true. A scheduled draft also needs explicit authorization
before a scheduler can publish it.

Is follower, following, or article search semantic?

No. All three use local SQLite FTS5. That keeps search fast, inspectable, and
free, but concrete words, handles, companies, and phrases work better than
questions that depend on synonyms or inferred meaning.

Does my data stay on my machine?

Drafts, schedules, monitor state, imported public data, and publish attempts
stay in local SQLite. Secrets stay in the keychain. ilo only sends the network
requests needed for the X and public-data actions you explicitly run.

What does ilo cost?

The package is free and open source under MIT. Your own X API access, provider
limits, and normal network costs still apply.

Documentation and support

Questions, bugs, and feature requests belong in
GitHub Issues. Security reports use
the private process in SECURITY.md.

Develop locally

Most users only need the npm package. Contributors can run the source checkout:

git clone https://github.com/iannuttall/ilo.git
cd ilo
pnpm install
pnpm build
node dist/cli.js --help

Run the full gate before opening a pull request:

pnpm lint
pnpm typecheck
pnpm test
pnpm build
pnpm pack --dry-run

Product, content, architecture, and agent rules live in
AGENTS.md.

License

The code is available under MIT. If ilo saves you time, you can
sponsor the project.

ilo