Skip to content
WireCatLabsPublic

About

Build a CLI that lets people and AI agents search a messenger, a mailbox or any service with a history. You write the adapter, cli-core adds the local store, search and an MCP server.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

3,349 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

cli-core: messages and mail your agent can search

@wirecat/cli-core

Build a CLI that lets people and AI agents search a messenger, a mailbox or any service with a history, in TypeScript on Node or Bun. You write the adapter that talks to the service, and cli-core gives it a local store with search, the shared commands and an MCP server.

import { type Messenger, mcpCommand, messagesCommand, run, searchCommand, settingsFor } from "@wirecat/cli-core/cli"
import { acmeAdapter } from "./adapter.js" // your code: the only part that speaks to Acme Chat

const app = { command: "acme", appName: "acme-cli", envPrefix: "ACME", description: "Acme Chat", version: "0.1.0" }
const settings = settingsFor(app)

const acme: Messenger = {
  app,
  provider: "acme",
  resolveSettings: settings.resolveSettings,
  connect: async () => acmeAdapter(),
  chatArgument: "a chat: its name or its Acme id",
}

process.exitCode = await run(process.argv.slice(2), {
  app,
  configuration: settings,
  commands: () => [messagesCommand(acme), searchCommand(acme), mcpCommand(acme)],
})
acme personal messages sync --all                  # every chat's history into the local store
acme personal search messages come --json=excerpt  # {"items":[{"excerpt":"are you coming?",…}],…}
acme personal mcp check                            # {"item":{"healthy":true,…,"tools":3,…},…}

That output is real, from this program with the in-memory fakeAdapter of @wirecat/cli-core/testing in place of Acme. The search found "are you coming?" from the word "come", with no network.

Built on it: tg-cli, max-cli, gcal-cli and 12 more WireCat CLIs, such as the mail and notes tool cli-memo, the WhatsApp tool, zoom-cli and drive-cli.

Install

npm install --save-exact @wirecat/cli-core

npm 7+ and pnpm also install its peers: @wirecat/cli-base in the range package.json names, and commander 15 or later. @napi-rs/canvas is optional, and charts need it only for PNG output. It runs on Node 22.16+ and 24+, and on Bun. Pin an exact version, because any release before 1.0 may break a caller (Build on it).

Architecture · Write an adapter · Query language · Messenger rules · API reference · Changelog · wirecat.dev

npm CI Node Bun License: Apache 2.0

Which package to install

flowchart LR
  cli["Your CLI"] -->|"keeps messages, mail or files to search"| core["@wirecat/cli-core"]
  cli -->|"any other CLI"| base["@wirecat/cli-base"]
  core --> base
  base --> runtime["Node or Bun"]
Loading

cli-core is for a tool that keeps what it reads in a local store and searches it. It is built on @wirecat/cli-base, the layer every CLI needs: two output streams, closed error codes, the keyring, injectable clocks and the query parser. cli-base is a peer dependency, so an install holds one copy. A CLI with nothing to store needs only cli-base.

Features

  • Search that finds the message, not only the word. One query language for every list and every source, a TypeScript port of the Apache Lucene 9.12.3 parsers: phrases, from:(alice OR bob), date:[2026-01-01 TO 2026-02-01}, size>10MB. Word forms in Russian, English and Spanish (встреча finds встречи), any three letters inside a word, and search by meaning when you opt in. A question over 100,341 synthetic messages took 54 ms at the median (measured, every search measurement). Syntax · grammar · image search
  • One store for every source. Messages from Telegram and MAX, mail, notes and meeting transcripts sit side by side in one SQLite file, wirecat.db, so one query searches all of them. Edits are kept as revisions and deletions as tombstones. Migrations only move forward, and an older CLI keeps reading a file a newer one migrated. Storage · why SQLite FTS5 and no daemon
  • An MCP server that leaves room in the agent's context. The shared commands reach an agent as 3 MCP tools: find a command, run a read, run a write. It runs over stdio, or over HTTP on 127.0.0.1 behind the owner's tunnel with a one-owner OAuth login.
  • Every write behind a guard. A permission level per command path (deny, readonly, ask or allow), a list of allowed recipients, and at most 30 sends an hour by default. A write whose outcome is unknown is never retried, and a retry under the same send id cannot send twice.
  • Knowledge, tasks and meetings across sources. What an agent proposes stays proposed until the owner accepts it. Tasks have project keys like RES-12, and a meeting transcript is kept by revision. Knowledge · Meetings · Mentions
  • Files and voice as text. Readers for PDF, Word, HTML and more, each loaded on first use, and speech recognition on your computer from a pinned model catalogue. Document workflows · Media archives

How it works

flowchart TB
  tools["tg · max · wa · memo · zm · drive"] --> interface
  subgraph core ["@wirecat/cli-core"]
    interface["Interface: CLI commands and MCP tools"] --> services["Services: one use case each"]
    services --> ports["Ports: MessengerAdapter · MeetingSource · TaskStore"]
    services --> store[("Store: one SQLite file, wirecat.db")]
    ports --> domain["Domain types"]
    store --> domain
  end
  adapters["Adapters, in each tool: Telegram, MAX, IMAP, Zoom…"] -. implement .-> ports
  core --> base["@wirecat/cli-base: output, exit codes, keyring, clocks, query parser"]
Loading

Five layers, and each calls only the layers below it: domain, adapters behind a port, ports, services, interface.

  • The CLI and the MCP server are two adapters over the same services. A command and its MCP tool answer with the same data, because one service produces it.
  • A port with one required core and optional groups. MessengerCore is what every messenger must do. Groups such as polls or forums are optional and reached through capability(). A messenger without a group refuses the command before it connects. It never crashes and never drops an option in silence.
  • Override a use case, not a command. A tool replaces one service through Messenger.services, and every command and tool that uses it follows.
  • The build keeps the lines. Biome import rules refuse any messenger library under src/, commander in a service, and the SQLite tables outside the store. Tests refuse a gap in the migration numbers and a search plan that reads an index once per message.

Build on it

A new messenger is three pieces: an adapter that implements MessengerCore (and any optional groups), a Messenger that describes it, and the contract cases run against it. The adapter guide walks through each one.

This runs as it is under vitest and gives 29 cases. fakeAdapter is the in-memory adapter the kit ships. Put your own adapter there, built over a fake client filled from seed. The ./testing kit is not stable yet.

import { contractCases, digitIds, fakeAdapter } from "@wirecat/cli-core/testing"
import { describe, it } from "vitest"

describe("the adapter keeps the port's promises", () => {
  for (const one of contractCases({ connect: (seed) => fakeAdapter(seed), ids: digitIds }))
    it(one.name, async (context) => {
      const result = await one.run()
      if (result) context.skip(result.skipped)
    })
})

Before 1.0, any release may break a caller. Releases are frequent, sometimes several a day, and any of them may change any entry point. The changelog lists every such change in its own section, with what to change. tg-cli and max-cli pin an exact version and move to a new one in their own pull request. Pin an exact version too. The full list of entry points and what each holds is in the API reference.

⚠ Errors are recognised by shape, not by class (isCliFailure). A package linked during development brings its own copy of cli-base, and an error built by one copy is not an instanceof the other's class.

Engineering standards

The WireCat CLI standards handbook in cli-base binds every WireCat CLI, and the messenger rules add what binds tg, max and wa. They measure themselves against POSIX, GNU, Command Line Interface Guidelines, the MCP specification and JSON Schema 2020-12, and say where they differ on purpose.

  • Tests that cannot touch real data. A sandbox keeps every test away from the owner's store, and no test may sleep. The coverage floor is 92% of lines, and at least half of every file.
  • Checked against the tools that use it. Every pull request builds tg-cli, max-cli, whatsapp-cli and cli-template against the branch. Which checks run on macOS and Windows is in Testing.
  • One shared toolchain. Biome, markdownlint, CSpell and Lefthook configs come from the WireCat standards, and CI fails when a copy drifts.

Development

pnpm install
pnpm lint && pnpm typecheck && pnpm test
pnpm smoke:bun    # the same exports, run under Bun

Releases go through bin/release from main. It refuses a dirty tree, runs every check, publishes to npm and tags v<version>. The steps and the release rules are in RELEASING.md.

Key documents

Document What it answers
Architecture The layers, the module map, the store internals and migrations, who consumes what
Document workflows Shared file ingestion, sync, scoped knowledge and extraction, and the ports a file provider supplies
Media archives Independent verified file copies, interruption recovery and opt-in daily timers
Write an adapter How to add a messenger: the port, the Messenger description, the contract cases
Messenger rules What binds tg, max and wa beyond the CLI standards handbook: parity, the option catalogue, bot
Glossary One word, one meaning across the tools
Query language · spec · Image search The search syntax and its exact grammar, and finding pictures by context and by what they show
Mentions · how they work Phones, e-mail, links, documents and names found in messages: search, review, rebuild, the tables and the rules
Storage The schema, the search indexes and the decisions behind them
Knowledge · Meetings Labels, links and proposals across sources, the meetings module and its providers
Testing · Parity audit The sandbox, the coverage floor, the checks across tg and max
Tool boundaries Which tool owns which command
API reference Every entry point and the detailed contract of each feature
Roadmap What is being built next for developers on this package
Changelog What each version changed, and what may break callers

History

Up to 0.261.0 the package was named @wirecat/cli-messaging, which is deprecated. The npm versions 0.0.0-stage, 0.0.0 and 0.18 to 0.20 of @wirecat/cli-core are deprecated too: they are placeholders and the old cli-base.

Licence

Apache License 2.0.

About

Build a CLI that lets people and AI agents search a messenger, a mailbox or any service with a history. You write the adapter, cli-core adds the local store, search and an MCP server.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages