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

• Getting started
• Publishing accounts
• CLI commands
• Following search
• Article monitoring
• Local MCP and agents
• TypeScript package
• X report library
• Privacy policy
• Security policy
• Contributing

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.