@longtable/cli

Researcher-facing CLI for LongTable.

LongTable is an npm-first, provider-neutral research harness. It keeps the core product contract in project files and shared packages, while Codex skills, Claude skills, and future MCP surfaces remain generated adapter artifacts.

The basic contract is:

1. seed the researcher profile once
2. create a workspace for each project
3. continue the research conversation inside that workspace
4. preserve decisions, tensions, and evidence as durable project state

Install

npm install -g @longtable/cli

For global npm installs, LongTable also bootstraps provider-native skill files:

• Codex skills are written to ~/.codex/skills/.
• Claude Code skills are written when the claude command is detected.
• LONGTABLE_POSTINSTALL_PROVIDERS=all npm install -g @longtable/cli installs both provider skill sets.
• LONGTABLE_SKIP_POSTINSTALL=1 npm install -g @longtable/cli skips the skill bootstrap.

MCP config writes are intentionally opt-in:

longtable mcp install --provider codex --write

During longtable init --flow interview, LongTable asks whether to configure MCP and whether provider-native team/subagent surfaces should be used when they are available. The stable fallback remains LongTable's sequential panel.

Primary Flow

longtable init --flow interview
longtable start
cd "<project-path>"
codex

Return later:

cd "<project-path>"
longtable resume
codex

What longtable start Creates

<project>/
  AGENTS.md
  CURRENT.md
  .longtable/
    project.json
    current-session.json
    state.json
    sessions/

Artifact Contract

• AGENTS.md: runtime guidance for Codex
• CURRENT.md: human-facing current view regenerated from state
• .longtable/project.json: stable project identity
• .longtable/current-session.json: current session cursor
• .longtable/state.json: layered memory state
• .longtable/sessions/: historical snapshots

Why This Shape

The CLI tries to keep the root simple for novice researchers while preserving enough structure for power users and downstream tooling.

The memory model distinguishes:

• explicit state
• working state
• inferred hypotheses
• open tensions
• narrative traces

This is how LongTable avoids turning tacit knowledge into fake certainty.

Commands

longtable init
longtable start
longtable resume --cwd "<project-path>"
longtable roles
longtable ask --cwd "<project-path>" --prompt "..."
longtable panel --prompt "..."
longtable codex install-skills
longtable claude install-skills

Useful structured routes for scripts and debugging:

longtable panel --prompt "review this methods section" --json
longtable review --role methods_critic,measurement_auditor --panel --prompt "review this methods section" --json
longtable ask --prompt "lt panel: show the disagreement before I commit" --json

Inside Codex

Natural language should be the default.

Explicit short forms are available when needed:

lt explore: Where should I narrow the question first?
lt review: What is weak in this claim?
lt panel: Show me the disagreement before I commit.
lt methods: Where is the design vulnerable?

Provider-native surfaces are available when installed:

longtable codex install-skills
longtable claude install-skills

Codex skills include longtable, longtable-panel, and generated role-specific skills such as longtable-methods-critic. If your Codex build exposes explicit skill shortcuts, $longtable is the manual entry. Do not depend on /prompts; current Codex builds may reject it.

Claude Code skills include longtable, longtable-panel, and generated role-specific skills such as longtable-methods-critic. They are adapter files generated from the LongTable role registry.

Panel Orchestration

Panel orchestration is for moments where disagreement matters: methods risk, measurement validity, theory fit, literature positioning, and claims that need challenge before they become project memory.

The CLI creates a provider-neutral PanelPlan and returns a planned PanelResult. When native subagents are unavailable, LongTable uses a stable sequential fallback prompt. That keeps the same research semantics available in Codex and Claude Code without making either provider's native question or agent tool the source of truth.

Inside a LongTable project workspace, panel planning also appends an InvocationRecord to .longtable/state.json, creates a pending follow-up QuestionRecord, and refreshes CURRENT.md.

longtable decide --answer evidence --rationale "Need citation support before continuing."

Default panel roles include:

• reviewer
• methods_critic
• measurement_auditor
• theory_critic

Use --role to constrain the panel when the research problem is already clear.

Evidence And Search Direction

LongTable should not behave like a generic web scraper. Research search should start from scholarly routes when the user needs literature discovery, citation verification, publication metadata, or evidence-backed research decisions.

Planned scholarly routes include arXiv, Crossref, OpenAlex, Semantic Scholar, PubMed/NCBI, ERIC, DOAJ, and Unpaywall. They have different setup requirements: some work without keys, some require a contact email, and some need API keys for reliable use.

Citation support should be checked explicitly. A reference can be useful as background while still failing to support the specific claim attached to it.

See:

• Research Search
• Evidence Policy
• LongTable Command Surface

Validation

npm install
npm run typecheck
npm run build