@texra-ai/cli 0.38.2 → 0.38.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +106 -196
  2. package/dist/bin/texra.js +1516 -938
  3. package/package.json +3 -2
package/README.md CHANGED
@@ -1,4 +1,4 @@
1
- # TeXRA: Multi-Agent AI Research Assistant for Theorists
1
+ # TeXRA
2
2
 
3
3
  [![VS Code Marketplace](https://vsmarketplacebadges.dev/version-short/texra-ai.texra.svg)](https://marketplace.visualstudio.com/items?itemName=texra-ai.texra)
4
4
  [![Installs](https://vsmarketplacebadges.dev/installs-short/texra-ai.texra.svg)](https://marketplace.visualstudio.com/items?itemName=texra-ai.texra)
@@ -9,225 +9,135 @@
9
9
  [![npm version](https://img.shields.io/npm/v/@texra-ai/cli?label=%40texra-ai%2Fcli)](https://www.npmjs.com/package/@texra-ai/cli)
10
10
  [![npm downloads](https://img.shields.io/npm/dm/@texra-ai/cli)](https://www.npmjs.com/package/@texra-ai/cli)
11
11
 
12
- > **🎓 Free for Researchers!** TeXRA offers a **Researcher Access Program** with
13
- > complimentary access to budget-friendly models from OpenAI, DeepSeek, Gemini,
14
- > and more—plus a hosted **Orchestrator** and a roster of remote specialist
15
- > agents. Sign in through the Profile view to get started—no API keys
16
- > required.
17
- >
18
- > The relay runs on sponsor credits. If TeXRA helps your research, please
19
- > consider supporting it via
20
- > [GitHub Sponsors](https://github.com/sponsors/texra-ai) or
21
- > [Buy Me a Coffee](https://buymeacoffee.com/texra.ai) to keep the program
22
- > open for everyone.
23
-
24
- **TeXRA is a multi-agent research assistant for theorists (Physics, Math, CS,
25
- Engineering, etc.).** Instead of chatting with a single model, you direct an
26
- **Orchestrator** that delegates to a team of specialists—researchers,
27
- numericists, reviewers, formalizers, LaTeX fixers, presenters—each with their
28
- own tools, prompts, and model. The result is a coordinated lab that drafts,
29
- reviews, computes, and formalizes rigorous scientific work alongside its LaTeX,
30
- code, figures, and PRs.
31
-
32
- ### One assistant, two surfaces
33
-
34
- The same agents, account, and model providers are available wherever you work:
35
-
36
- | | **VS Code extension** | **Terminal CLI** |
37
- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
38
- | Best for | Interactive writing, side-by-side diffs, figure previews | Scripts, CI, remote/headless machines, the keyboard-first |
39
- | Install | [Marketplace](https://marketplace.visualstudio.com/items?itemName=texra-ai.texra) / [Open VSX](https://open-vsx.org/extension/texra-ai/texra) | `npm install -g @texra-ai/cli` |
40
- | Drive it with | Sidebar chat + the **progress board** | `texra chat` (TUI) and `texra run` (headless) |
41
-
42
- Pick whichever fits the moment—both run the same teams on the same `.tex`
43
- projects. The deeper walkthroughs live at
44
- [texra.ai](https://texra.ai) and the
45
- [full documentation](https://texra.ai/guide/).
46
-
47
- ## Why TeXRA
48
-
49
- - **Orchestrator-first** – the **Orchestrator** decomposes your task,
50
- delegates to specialists in parallel, captures their outputs as diffs, and
51
- presents proposals you approve before they touch your files. Follow-ups
52
- during delegation are queued, sub-agent runs can be inspected, waited on,
53
- resumed, or terminated, and the orchestrator builds long-term memory across
54
- sessions.
55
- - **Curated team presets** – switch to **Physicist**, **Mathematician**,
56
- **Computer Scientist (ML)**, or **Lean Project** in one click from the
57
- Multi-Agent settings tab, or with `texra multi-agent run <preset>` in the
58
- terminal. Each preset is a preconfigured roster of workflow and tool-use
59
- agents tuned for that discipline; you can also save your own.
60
- - **A full cast of specialists** – locally bundled tool-use agents include
61
- `research`, `numerics`, `review`, `presenter`, `latexFixer`, `latexDiff`,
62
- `creator`, `lean`, `chat`, and the **Setup Wizard** (`setup`); workflow
63
- agents include `correct`, `polish`, `merge`, `ocr`, `transcribe_audio`,
64
- `paper2slide`, and `paper2poster`. Signing in unlocks remote specialists—
65
- `orchestrator`, `search`, `simplifier`, `criticize`, `devise`, `apply`,
66
- `generic`, `progressCheck`, and the Lean `leanOrchestrator` /
67
- `leanBlueprint` / `leanSearch` / `leanSimplifier` line.
68
- - **Tools that touch your project** – tool-use agents read and edit
69
- workspace files, run shell commands, drive LaTeX builds, work with Git and
70
- GitHub PR subscriptions, and can delegate reasoning turns to the Codex
71
- CLI—each tool call gated by per-stream approval (with an optional YOLO
72
- bypass).
73
- - **Live, persistent runs** – watch reasoning, tool calls, sub-agent file
74
- diffs, and per-run token usage and cost stream in real time—on the VS Code
75
- **progress board** or in the `texra chat` terminal UI. Each surface saves its
76
- runs so you can reopen and resume them later: via **Show Agent Execution
77
- History** and **Resume Tool-Use Agent** in VS Code, or `texra history` and
78
- `texra resume <id>` in the terminal. Finished outputs can be archived into
79
- the workspace's `History/` directory.
80
- - **Odyssey mode (experimental)** – let a tool-use agent run a long task to
81
- completion on its own. A configurable budget auto-pauses the run for your
82
- approval before going further, and a dedicated panel shows progress so
83
- you can step in at any time. Off by default; enable it with the
84
- `texra.experimental.odyssey.enabled` VS Code setting.
85
- - **Model flexibility with guardrails** – mix and match per agent: OpenAI
86
- (incl. GPT-5.5 and GPT Pro), Anthropic (incl. Claude Opus 4.7), Google
87
- Gemini, DeepSeek, xAI Grok, Moonshot Kimi, Alibaba Qwen (DashScope),
88
- Zhipu GLM, MiniMax, OpenRouter, and custom endpoints—with context
89
- management, retry/backoff, parallel-tool-call limits, and cost monitoring
90
- all configurable.
91
-
92
- ## Built-in Agent Teams
93
-
94
- | Team | What the team does |
95
- | --------------------------- | ------------------------------------------------------------------------------------------------------ |
96
- | **Physicist** | Analytical derivations, numerical experiments, literature search, slide drafting, and critical review. |
97
- | **Mathematician** | Proofs, Lean 4 formalization, research, and LaTeX correction. |
98
- | **Computer Scientist (ML)** | Algorithm design, experiments and ablations, literature search, critical review, and reproducibility. |
99
- | **Lean Project** | Lean 4 projects—theorem search, tactic simplification, and blueprint-driven formalization. |
100
-
101
- Switch teams from the Multi-Agent tab in Settings (or `texra multi-agent` in
102
- the terminal), or build your own roster of workflow and tool-use agents. Teams
103
- that include remote specialists (e.g. the
104
- Orchestrator, `search`, `simplifier`) require sign-in or your own API keys
105
- configured for the providers those agents use.
106
-
107
- ## Quick Start
108
-
109
- Both surfaces share the same sign-in and agents, so set up whichever you'll
110
- use—or both.
111
-
112
- ### In VS Code
113
-
114
- 1. Install the extension from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=texra-ai.texra)
115
- or [Open VSX](https://open-vsx.org/extension/texra-ai/texra).
116
- 2. Launch the **Setup Wizard**. Pick whichever is easiest:
117
- - Click the **🚀 TeXRA: Get Started** pill in the status bar (shown
118
- automatically until you sign in or add an API key).
119
- - Click **Run the setup assistant agent** in the Getting Started banner
120
- at the top of the TeXRA sidebar.
121
- - Open VS Code's **Welcome / Walkthroughs** page and pick **TeXRA:
122
- Getting Started** — Step 1 is a one-click button.
123
- - Or, from the command palette, run
124
- **`TeXRA: Run Setup Assistant Agent (Setup Wizard)`**.
125
-
126
- The Setup Wizard diagnoses your environment, installs missing LaTeX
127
- tooling, helps you sign in or add an API key, and verifies you're ready
128
- to run agents—asking before every command and explaining what it's
129
- doing. It can hand off interactive `sudo` prompts and installers to your
130
- VS Code terminal.
131
-
132
- 3. Pick an agent **team** in Settings → Multi-Agent (Physicist,
133
- Mathematician, CS/ML, or Lean Project), or stay with the default lineup.
134
- 4. Open the TeXRA sidebar, select the **Orchestrator** (or any agent),
135
- describe your task, and approve the proposals it routes to specialists.
136
- Watch progress, file diffs, and live reasoning on the **progress board**,
137
- and follow up at any time—messages are queued for whichever sub-agent
138
- needs them.
139
-
140
- New here? Use the **Create Sample Project** button in the Getting Started
141
- banner (also available as `TeXRA: Create Sample Project` from the command
142
- palette) to spin up a fully configured workspace.
143
-
144
- ### In the terminal
145
-
146
- Run the same agents on your `.tex` projects without an editor—ideal for
147
- scripts, CI, and remote machines.
12
+ A LaTeX research assistant for VS Code and the terminal. Multi-agent
13
+ workflows for writing, reviewing, formalizing, and rendering academic
14
+ work — with every change returned as a diff you approve.
15
+
16
+ ## Install
148
17
 
149
18
  ```sh
150
- npm install -g @texra-ai/cli # requires Node.js >= 22
19
+ # VS Code (or Cursor, Windsurf, Antigravity)
20
+ code --install-extension texra-ai.texra
151
21
 
152
- texra login # Researcher Access sign-in; or set <PROVIDER>_API_KEY and use --api-mode personal
153
- texra doctor # verify environment, sign-in, models, and LaTeX tooling
22
+ # Terminal — requires Node.js 22+
23
+ npm install -g @texra-ai/cli
154
24
  ```
155
25
 
156
- Then drive a whole research team from the prompt:
26
+ Sign in with GitHub or Google for hosted access (no key management
27
+ required), or set `<PROVIDER>_API_KEY` to use your own credentials.
28
+
29
+ ### Researcher Access Program
30
+
31
+ Academic researchers can sign in for complimentary hosted access to
32
+ a curated set of budget-friendly models — enough to run the
33
+ Orchestrator and the full roster of hosted specialists on real work,
34
+ without managing provider keys or paying per-token rates. Sign in
35
+ through the Profile view in VS Code, or `texra login` in the
36
+ terminal.
37
+
38
+ The program is sustained by the community. If TeXRA helps your
39
+ research, consider supporting it via
40
+ [GitHub Sponsors](https://github.com/sponsors/texra-ai) or
41
+ [Buy Me a Coffee](https://buymeacoffee.com/texra.ai) to keep it open
42
+ for everyone.
43
+
44
+ ## Run
45
+
46
+ In VS Code: open a `.tex` file, click the TeXRA icon, pick
47
+ **Orchestrator** or another agent, type a task. The Setup Wizard runs
48
+ on first launch and checks your environment.
49
+
50
+ In the terminal:
157
51
 
158
52
  ```sh
159
- texra # interactive launcher: pick a chat, team, or run to resume
160
- texra chat # interactive tool-use session (Orchestrator and specialists)
161
- texra run polish --input paper.tex --output paper.polished.tex --print
53
+ texra chat # interactive tool-use session
54
+ texra run polish --input paper.tex # one-shot workflow
55
+ texra multi-agent run physicist # named team
162
56
  ```
163
57
 
164
- The CLI exposes the full toolkit—`texra agents`, `models`, `tools`, and
165
- `multi-agent` to inspect and launch teams; `texra history` and `texra resume`
166
- to revisit or re-run past work; `texra init` to drop a project `.texra/config.json`.
167
- For automation, every headless command takes `--output-format json|ndjson` and
168
- `--approval-policy never|ask|yolo`. Run `texra --help` or see the
169
- [documentation](https://texra.ai/guide/) for the full command reference.
58
+ Run history and agent settings are shared between both surfaces.
170
59
 
171
- ## Requirements
60
+ ## Teams
61
+
62
+ Four built-in presets cover the most common research disciplines:
63
+
64
+ | Team | Built for |
65
+ | --------------------------- | -------------------------------------------------------------------------------- |
66
+ | **Physicist** | Analytical derivations, numerical experiments, literature search, slide drafting |
67
+ | **Mathematician** | Proofs, Lean 4 formalization, research, LaTeX correction |
68
+ | **Computer Scientist (ML)** | Algorithm design, experiments and ablations, literature, reproducibility |
69
+ | **Lean Project** | Mathlib search, tactic simplification, blueprint-driven formalization |
172
70
 
173
- - **VS Code** 1.105+ for the extension (also runs in compatible editors such
174
- as Cursor, Windsurf, and Google Antigravity), **or Node.js 22+** for the
175
- terminal CLI
176
- - **LaTeX distribution** (TeX Live, MiKTeX, or MacTeX) for compilation and
177
- related tooling
178
- - **Perl** (required by `latexindent` and `latexdiff`)
179
- - **Optional**: GraphicsMagick/ImageMagick and Ghostscript for PDF and image
180
- processing; `git` for repository-aware features; `gh` and a Codex CLI for
181
- GitHub PR and Codex integrations; Lean 4 + `lake` for the Lean Project team
71
+ Pick a team in **Settings → Multi-Agent**, or with `texra multi-agent
72
+ run <preset>`. Or define your own roster in YAML.
182
73
 
183
- The Setup Wizard checks for and helps install most of the above for you.
74
+ ## Agents
184
75
 
185
- ## Configuring Models
76
+ **Workflow agents** write to disk and produce reviewable diffs:
77
+ `polish`, `correct`, `merge`, `ocr`, `transcribe_audio`, `paper2slide`,
78
+ `paper2poster`.
186
79
 
187
- Sign in to the Researcher Access Program—via the Profile view in VS Code or
188
- `texra login` in the terminal—to use the hosted Orchestrator and remote
189
- specialists. To bring your own keys instead, the extension reads them from the
190
- **`TeXRA: Set API Key`** command (stored in VS Code's encrypted SecretStorage)
191
- or a workspace `.env` file it loads automatically; the CLI reads the same
192
- `<PROVIDER>_API_KEY` variables from your environment when run with
193
- `--api-mode personal`:
80
+ **Tool-use agents** work conversationally with file, shell, and search
81
+ access: `research`, `numerics`, `review`, `presenter`, `latexFixer`,
82
+ `latexDiff`, `creator`, `lean`, `chat`, `setup`.
83
+
84
+ **Hosted specialists** (signed-in users): `orchestrator`, `search`,
85
+ `simplifier`, `criticize`, `devise`, `apply`, `generic`,
86
+ `progressCheck`, and the Lean line — `leanOrchestrator`,
87
+ `leanBlueprint`, `leanSearch`, `leanSimplifier`.
88
+
89
+ Every tool call is gated by per-stream approval. Optional YOLO mode
90
+ skips approval for autonomous runs.
91
+
92
+ ## Models
93
+
94
+ Bring your own keys for OpenAI, Anthropic, Google Gemini, DeepSeek,
95
+ xAI Grok, Moonshot Kimi, Alibaba Qwen, Zhipu GLM, MiniMax, OpenRouter,
96
+ or any OpenAI-compatible endpoint. Each agent in a team can run a
97
+ different model — pair a flagship reasoner for orchestration with
98
+ cheaper, faster models for routine sub-tasks.
99
+
100
+ In the extension, run **`TeXRA: Set API Key`** (stored in VS Code's
101
+ encrypted SecretStorage) or add a workspace `.env`:
194
102
 
195
103
  ```env
196
- OPENAI_API_KEY=your_openai_key_here
197
- ANTHROPIC_API_KEY=your_anthropic_key_here
198
- GOOGLE_API_KEY=your_google_key_here
199
- DEEPSEEK_API_KEY=your_deepseek_key_here
200
- XAI_API_KEY=your_xai_key_here
201
- OPENROUTER_API_KEY=your_openrouter_key_here
104
+ OPENAI_API_KEY=…
105
+ ANTHROPIC_API_KEY=…
106
+ GOOGLE_API_KEY=…
202
107
  ```
203
108
 
204
- Other supported providers follow the same `<PROVIDER>_API_KEY` convention:
205
- `MOONSHOT_API_KEY`, `DASHSCOPE_API_KEY` (Qwen), `MINIMAX_API_KEY`,
206
- `GLM_API_KEY`. Each
207
- agent in a team can use a different model, so you can pair a flagship reasoner
208
- for the orchestrator with cheaper, faster models for routine sub-tasks. See
209
- the [installation guide](https://texra.ai/guide/installation.html) and the
210
- [models guide](https://texra.ai/guide/models.html) for details.
109
+ In the CLI, export the same variables in your shell and run with
110
+ `--api-mode personal`.
111
+
112
+ ## Requirements
113
+
114
+ - **VS Code 1.105+** (also runs in Cursor, Windsurf, Antigravity), or
115
+ **Node.js 22+** for the CLI
116
+ - **LaTeX distribution** (TeX Live, MiKTeX, or MacTeX)
117
+ - **Perl** (for `latexindent` and `latexdiff`)
118
+ - Optional: ImageMagick + Ghostscript (for PDF/image processing),
119
+ `git`, `gh`, Codex CLI, Lean 4 + `lake`
120
+
121
+ The Setup Wizard checks for and helps install most of the above.
122
+
123
+ ## Documentation
211
124
 
212
- ## Customization
125
+ - [Installation](https://texra.ai/guide/installation)
126
+ - [Quick Start](https://texra.ai/guide/quick-start)
127
+ - [Built-in Agents](https://texra.ai/guide/built-in-agents)
128
+ - [Polish a draft](https://texra.ai/guide/workflows/polish-a-draft) — workflow example
129
+ - [Models](https://texra.ai/guide/models)
130
+ - [Custom Agents](https://texra.ai/guide/custom-agents)
213
131
 
214
- Configure agents, prompts, models, and reliability policy in VS Code settings
215
- or the unified Settings view (Memory, History, Models, Agents, Multi-Agent,
216
- Tools, Git, LaTeX tabs). The Multi-Agent tab covers team presets, parallel
217
- tool-call limits, compaction thresholds, retry/backoff, and the orchestrator
218
- kill toggle. In the terminal, `texra init` writes a project
219
- `.texra/config.json` with the same knobs, and any setting can be overridden
220
- per run with a command-line flag. Power users on either surface can define new
221
- workflow or tool-use agents in YAML or register new model handlers.
132
+ Full docs at [texra.ai/guide](https://texra.ai/guide/).
222
133
 
223
- ## Support & Feedback
134
+ ## Support
224
135
 
225
- Report issues and feature requests on the
226
- [GitHub issues page](https://github.com/texra-ai/texra-issues/issues) or email
227
- [contact@texra.ai](mailto:contact@texra.ai).
136
+ Issues and feature requests: [GitHub](https://github.com/texra-ai/texra-issues/issues).
137
+ Contact: [contact@texra.ai](mailto:contact@texra.ai).
228
138
 
229
139
  ## License
230
140
 
231
141
  © TeXRA Team 2025–2026. All rights reserved.
232
142
 
233
- [Terms of Service](https://texra.ai/terms) · [Provider List](https://texra.ai/providers)
143
+ [Terms of Service](https://texra.ai/terms) · [Provider list](https://texra.ai/providers)