walter-axi

September 15, 2026 · View on GitHub

AXI-compliant CLI for WalterWrites — detect AI-generated patterns, humanize drafts with locked keywords, and batch QA content through the Walter MCP server. Built to the AXI spec (axi/1.0-2026-07): token-efficient TOON output, structured errors, contextual next steps, and explicit --confirm gates on credit-consuming writes.

walter-axi wraps Walter's hosted MCP server (https://mcp-server.walterwrites.ai/mcp) as a scriptable, headless CLI. It is a community integration and is not affiliated with WalterWrites.

Install

npm install
npm run build
npm link
walter-axi --help

Without linking, run node bin/walter-axi.js. Once published, npx -y walter-axi <command> works with no install.

Install the agent skill

The repo bundles an installable Agent Skill at skills/walter-axi/ — the same guidance as the CLI's home view, loadable on demand in Claude Code, Codex, Cursor, OpenCode, and 70+ other agents:

npx -y skills@latest add brycehamrick/walter-axi --skill walter-axi -g

Drop -g for a project-scoped install. The skill is generated from src/skill.ts (npm run skill:gen) so it never drifts from the CLI. Prefer the walter-axi setup hooks ambient session context when your harness supports hooks — the skill is the lower-overhead alternative, and you only need one.

skills.sh

Authentication

The Walter MCP server requires OAuth 2.1. walter-axi runs a one-time browser approval and then stays headless forever:

walter-axi auth login     # opens the browser; approves scopes tools:read tools:write
walter-axi auth status    # shows connection state and token source
walter-axi auth logout    # revokes tokens and removes the local credential file
  • Discovery, dynamic client registration (RFC 7591, public client), PKCE S256, silent refresh, and revocation all follow the endpoints the server advertises at /.well-known/oauth-authorization-server.
  • Tokens are stored in ~/.config/walter-axi/config.json with 0600 permissions (XDG_CONFIG_HOME is honored) and are never printed.
  • For headless/CI use, WALTER_ACCESS_TOKEN in the environment overrides stored tokens. That variable name is this CLI's own documented interface — Walter's public docs do not define one for an already-issued token.

Commands

# Free reads
walter-axi                          # live account dashboard (content-first home view)
walter-axi account                  # plan, credits, per-request word limit
walter-axi detect draft.md          # AI-pattern score, verdict, high-risk spans, notes
walter-axi detect draft.md --granularity sentence --full

# Credit-consuming writes (require --confirm)
walter-axi humanize draft.md --confirm \
  --phrase "enterprise content pipeline" --keyword "local seo" \
  --tone "expert, direct" --audience "B2B SaaS buyers" --out final.md
walter-axi humanize draft.md --mode safe --confirm --full
walter-axi pipeline draft.md --confirm --out final.md   # detect -> humanize -> detect

# Batch: JSONL in (one {"id","text",...} object per line, max 25 items)
walter-axi batch items.jsonl --confirm --out-dir ./out

# Ambient context (opt-in session hooks for Claude Code, Codex, OpenCode)
walter-axi setup hooks
walter-axi setup hooks --remove

Text input is a file path or - for piped stdin. Output text is a truncated preview by default; --full prints it complete and --out <file> (humanize/pipeline) or --out-dir <dir> (batch) writes it to disk without overwriting existing files unless --force is passed.

Batch items accept id, text, and optional mode, tone, audience, reading_level, phrases, keywords, entities, disallowed, brand_voice_id. Items must be 50–5000 words (a Walter requirement). Command flags become defaults that items can override.

Humanize results surface pre-computed preservation aggregates (phrases: 2/3 preserved) and list every missing phrase/keyword/entity, so a dropped SEO phrase is visible without re-running anything. pipeline adds before/after detection scores and the delta in one call chain.

Markdown front matter. detect, humanize, and pipeline strip leading YAML front matter (--- … ---) before any API call — metadata is not prose, and a document with front matter reliably reads as near-certain AI otherwise. humanize/pipeline re-attach it at the top of --out files so the result stays a complete document. Batch JSONL items are raw text and are never stripped.

Integrity check. Every humanize/pipeline result compares the output against its input: heading/link/shortcode counts (integrity), the word ratio, and integrity_flags like headings-dropped, links-dropped, shortcodes-dropped, or content-shrunk, plus missing_links/missing_shortcodes lists. The humanizer can silently drop sections on long documents; these flags make that visible before you publish. Detection span reasons are score-derived, so a score-100 span is never labeled "Low AI probability".

Word limits. The API accepts items of 50–5000 words, but plans cap words per request below that (a Pro plan caps at 1,500). account shows your exact limit; detect and humanize preflight it locally and fail with the real number instead of a server-side rejection. Split long documents into chunks under the limit at heading boundaries.

Safety gate

humanize, batch, and pipeline consume Walter credits. They refuse to run — before any network request — unless --confirm is present. The gate authorizes one invocation only; there are no prompts and no remembered consent. Reads (account, detect, auth status, setup status) never require confirmation.

Output and exit codes

Compact TOON is the default on stdout:

humanized:
  words: 99 -> 127
  phrases: 0/1 preserved
  keywords: 0/0 preserved
  entities: 0/0 preserved
  quality_flags: none
missing_phrases[1]:
  operational efficiency
preview: "As businesses strive to keep pace...(truncated, 743 chars total - use --full for the complete text, or --out <file> to save it)"
help[2]:
  Run `walter-axi humanize <file|-> --confirm --out <file>` to save the full text
  Run `walter-axi pipeline <file|-> --confirm` for before/after scores in one pass

Data commands accept --json. Errors are structured on stdout with a code and help[] suggestions. Exit codes: 0 success (including no-ops and partial batch results reported cleanly), 1 runtime or Walter API error (including a batch where any item failed), 2 usage/validation error, including unknown flags.

Development

npm test             # hermetic: no network, no credentials (MCP and OAuth are mocked)
npm run typecheck
npm run skill:check  # fails if skills/walter-axi/SKILL.md drifts from src/skill.ts

UNRESOLVED / intentionally not implemented

  • Brand voice management: brand voices are referenced by --brand-voice <id> / brand_voice_id, but the MCP server exposes no tool to list or create them. Ids must come from the Walter workspace UI.
  • Detect-on-URL or file-format conversion: the MCP server accepts plain text only; there is no document ingestion.
  • Language selection: the MCP tools expose no language parameter; Walter infers it.
  • Token issuance without a browser: there is no device-code or client-credentials grant on the server. Headless environments should use WALTER_ACCESS_TOKEN with a token obtained from an interactive login.

Official documentation used

Reviewed against the live service rather than assumptions:

  • Walter MCP server: https://mcp-server.walterwrites.ai/mcp (tool schemas and response shapes verified directly)
  • OAuth discovery: /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server on the same host
  • Community guide: waltermcp.com
  • Walter product pages

Credits

  • AXI — the agent-ergonomic CLI design principles this tool follows
  • axi-sdk-js — dispatch, TOON output, self-update, session hooks
  • otter-axi (MIT, Jarvus Innovations) — the loopback-OAuth-over-hosted-MCP pattern this CLI adapts

License

MIT