@ankit6055/lex 0.0.0-stage → 0.3.1

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 (4) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +153 -2
  3. package/dist/cli.js +65033 -0
  4. package/package.json +51 -4
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Lex contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,154 @@
1
- # Temporary Holding Version
1
+ # Lex
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ ![Lex running in the terminal, showing the startup banner, selected model, and prompt](docs/lex-terminal.png)
4
+
5
+ Website: [lex-agent-phi.vercel.app](https://lex-agent-phi.vercel.app) · Install: `npx @ankit6055/lex` · [Watch the Lex demo on Google Drive](https://drive.google.com/file/d/1RlC1GBGPRzCb9zrqRU85cTlKMXddtYzA/view?usp=sharing)
6
+
7
+ Lex is an open-source AI coding agent for your terminal. It reads and edits project files, runs commands with your approval, and streams its work as it goes. Use a hosted model with your own API key or connect to a local model through Ollama or LM Studio.
8
+
9
+ - **Work interactively or run once.** Use the terminal UI for ongoing work, or pass a prompt on the command line for a single streamed response.
10
+ - **Switch models during a task.** The new model takes over at the next agent step and keeps the conversation. Run the same task on several models to compare their results and diffs.
11
+ - **Control changes.** Review edits and commands, use plan mode to investigate, and restore project files with `/undo`.
12
+ - **Teach Lex your project.** Add repository instructions, save durable facts, and keep reusable workflows in skills.
13
+
14
+ ## Get started
15
+
16
+ Use Node.js 22 or later to run the bundled CLI, Bun to build it from source, and Git for checkpoints and model comparisons.
17
+
18
+ ```bash
19
+ git clone https://github.com/Ankit6055/lex.git
20
+ cd lex
21
+ bun install
22
+ bun run build
23
+
24
+ node dist/cli.js login
25
+ node dist/cli.js --cwd /path/to/project
26
+ ```
27
+
28
+ You can also set a provider's environment variable, such as `AI_GATEWAY_API_KEY`, before launching. For local models, start the server and specify a model that supports tool calling.
29
+
30
+ ```bash
31
+ node dist/cli.js --cwd /path/to/project --model ollama:qwen3:8b
32
+ node dist/cli.js --cwd /path/to/project --readonly "Explain how tests are organized"
33
+ ```
34
+
35
+ The examples below use `lex` for the CLI. In a source checkout, substitute `node /path/to/lex/dist/cli.js`. To make `lex` available from any directory, run `npm install -g .` from the built checkout.
36
+
37
+ ## Terminal UI
38
+
39
+ Run `lex` without a prompt to start an interactive session. The composer supports multiline input, prompt history, file and command completion, and follow-ups queued while the agent works. The transcript shows tool calls and results, and the status area shows elapsed time, output tokens, and generation speed when available.
40
+
41
+ | Input | What it does |
42
+ |---|---|
43
+ | `/` | Find slash commands. |
44
+ | `@filename` | Complete a project file reference in your prompt. |
45
+ | `# fact` | Save a durable fact to project memory. |
46
+ | `!command` | Run a shell command yourself. Lex attaches a capped excerpt of its output to your next prompt. |
47
+ | `Shift+Tab` | Cycle approval modes. |
48
+ | `Ctrl+L` / `Ctrl+P` | Open the model picker / cycle through suggested models. |
49
+ | `Ctrl+G` | Edit the current prompt in `$VISUAL` or `$EDITOR`. |
50
+ | `Alt+Enter` / backslash then Enter | Start a new line. |
51
+ | `Esc` | Interrupt an active turn when the composer menu is closed. |
52
+ | `Ctrl+C` / `Ctrl+D` | Clear a draft or interrupt with `Ctrl+C`. At an idle, empty prompt, press `Ctrl+C` twice or `Ctrl+D` once to quit. |
53
+ | `?` on an empty prompt | Show shortcuts. |
54
+
55
+ | Command | What it does |
56
+ |---|---|
57
+ | `/model [spec]` | Pick or switch models. The conversation stays open and the selection is saved as your default. |
58
+ | `/compare [task]` | Pick two or more models and run the same task on each. |
59
+ | `/plan`, `/edits`, `/yolo` | Toggle plan, accept-edits, or bypass mode. |
60
+ | `/undo` | Restore files from the checkpoint before the most recent recorded turn that changed files. |
61
+ | `/clear`, `/new` | Start a fresh conversation. |
62
+ | `/memory`, `/remember <fact>` | View or add project memory. |
63
+ | `/todo`, `/usage` | Inspect the current checklist or session usage. |
64
+ | `/login`, `/help`, `/exit` | Save a provider key, see help, or quit. |
65
+
66
+ Set `LEX_PLAIN=1` to use the line-based interface. Lex also selects it when input or output is piped. In that interface, `/readonly` toggles read-only mode and `/model` shows a numbered list. Use `NO_COLOR=1` to disable colors. In one-shot mode the response goes to stdout, with tool activity and usage on stderr. Use `lex --help` for flags, including `--cwd`, `--max-steps` (25 by default), and `-m` / `--model`.
67
+
68
+ ## Approvals and undo
69
+
70
+ | Mode | Agent behavior |
71
+ |---|---|
72
+ | Ask (default) | Prompts for file changes and shell commands outside the built-in allowlist. Approval can apply once or for the session. |
73
+ | Accept edits (`/edits`) | Automatically allows file writes and edits. Shell approvals still apply. |
74
+ | Plan (`/plan` or `--readonly`) | Guides the model to investigate and propose changes. The approval gate blocks file writes, edits, and shell commands outside the allowlist. |
75
+ | Bypass (`/yolo` or `--yolo`) | Runs agent tools without approval prompts. |
76
+
77
+ File tools check that paths resolve inside the project root. Shell commands run with your user permissions. The `!` shortcut runs commands you type directly.
78
+
79
+ Before a turn, Lex can snapshot the project in a private Git repository under `~/.lex/checkpoints/`. `/undo` restores files captured by the checkpoint and removes files added since it. It can also revert manual edits made since that checkpoint. Checkpoints use Git's file selection and work for projects without their own Git repository.
80
+
81
+ ## Compare models
82
+
83
+ ```bash
84
+ lex compare --models gateway:anthropic/claude-sonnet-5.5,gateway:openai/gpt-6.2-sol \
85
+ --check 'npm test' --diff "Add input validation to createUser"
86
+ ```
87
+
88
+ In a terminal you can omit `--models` to open the picker. Lex runs each model in parallel in a separate temporary Git copy and displays its status, token usage, generation speed when available, estimated cost, and recent tool activity. Press `Esc` to stop the race. Piped runs and `LEX_PLAIN=1` use line-by-line logs.
89
+
90
+ Use `--check '<command>'` to score the result in each copy. Lex defaults to `npm test` when the project's `package.json` defines a test script. The final report shows check results, the fastest qualifying model, the cheapest qualifying model when pricing is available, and paths to the copies. Failed checks include an output excerpt. Costs are estimates based on AI Gateway catalog prices for supported models.
91
+
92
+ Use `--diff` to include full diffs. Compare runs agents unattended and links an existing `node_modules` directory from the source project.
93
+
94
+ ## Providers and configuration
95
+
96
+ Lex supports 19 built-in providers. Use `lex login` to save a key in `~/.lex/auth.json` with owner-only permissions, or set the matching environment variable. Environment keys take precedence.
97
+
98
+ | Provider ID | API key variable | Provider ID | API key variable |
99
+ |---|---|---|---|
100
+ | `gateway` | `AI_GATEWAY_API_KEY` | `groq` | `GROQ_API_KEY` |
101
+ | `anthropic` | `ANTHROPIC_API_KEY` | `cerebras` | `CEREBRAS_API_KEY` |
102
+ | `openai` | `OPENAI_API_KEY` | `together` | `TOGETHER_API_KEY` |
103
+ | `openrouter` | `OPENROUTER_API_KEY` | `fireworks` | `FIREWORKS_API_KEY` |
104
+ | `google` | `GEMINI_API_KEY` | `moonshot` | `MOONSHOT_API_KEY` |
105
+ | `xai` | `XAI_API_KEY` | `zai` | `ZAI_API_KEY` |
106
+ | `deepseek` | `DEEPSEEK_API_KEY` | `minimax` | `MINIMAX_API_KEY` |
107
+ | `mistral` | `MISTRAL_API_KEY` | `nvidia` | `NVIDIA_API_KEY` |
108
+ | `huggingface` | `HF_TOKEN` | `ollama`, `lmstudio` | Local, no key |
109
+
110
+ Run `lex models` to see available model specs. Use `provider:model` for an exact choice, a provider name such as `deepseek` for its default, or a recognized bare model ID. For example, a bare `claude-*` model uses Anthropic when an Anthropic key is configured and AI Gateway otherwise.
111
+
112
+ Model selection checks `--model`, then `LEX_MODEL`, then `defaultModel` in `~/.lex/config.json`, followed by the first configured hosted provider. Set `LEX_HOME` to change the directory that holds configuration, credentials, user skills, and checkpoints.
113
+
114
+ Add a custom OpenAI-compatible endpoint in `~/.lex/config.json`. Set `apiKeyEnv` when the endpoint requires a key. OpenAI-compatible adapters also accept a `<PROVIDER>_BASE_URL` override, such as `OLLAMA_BASE_URL`.
115
+
116
+ ```json
117
+ {
118
+ "defaultModel": "vllm:qwen3",
119
+ "providers": {
120
+ "vllm": {
121
+ "baseURL": "http://localhost:8000/v1",
122
+ "models": ["qwen3"]
123
+ }
124
+ }
125
+ }
126
+ ```
127
+
128
+ ## Project context and tools
129
+
130
+ - **Instructions.** Lex looks for the nearest `AGENTS.md`, `CLAUDE.md`, or `LEX.md` between the working directory and the Git root.
131
+ - **Memory.** Project facts live in `.lex/memory.md` and are loaded into future sessions. Use `# fact`, `/remember`, or ask the agent to remember a convention.
132
+ - **Skills.** Put a `SKILL.md` with a name, description, and instructions in `skills/<name>/` in the project or under `~/.lex/skills/<name>/`. Lex lists the names and descriptions in the prompt and loads the full instructions on demand. Project skills take precedence when names match.
133
+ - **Tools.** The agent can list, search, read, write, and edit files, run shell commands, track todos, and ask questions. The `task` tool delegates exploration to a read-only subagent and can use a cheaper model when one is available.
134
+
135
+ The [agent loop](src/agent.ts) runs tool calls in order. It turns earlier tool exchanges into short notes and keeps current-turn results until the context budget requires pruning. For implementation details, see the [session](src/session.ts), [terminal UI](src/ui/), and [provider registry](src/providers.ts).
136
+
137
+ ## Develop and verify
138
+
139
+ ```bash
140
+ bun install
141
+ bun run dev
142
+ bun run typecheck
143
+ bun test
144
+ bun test test/properties.test.ts
145
+ bun run build
146
+ bash scripts/smoke.sh
147
+ bash scripts/smoke.sh --live
148
+ ```
149
+
150
+ The default test suite covers unit behavior, CLI and agent integration, regressions, and property tests. Property tests run 500 generated cases per property. Replay a failure with the reported `seed` and `path` in that test's `fc.assert` options. The optional live smoke test uses a configured provider key and verifies a read-only tool round trip from a clean package install.
151
+
152
+ Try the [toy repository](examples/toy-repo) for a small project with a failing test. The [build plan](plan.md) describes how the core was designed.
153
+
154
+ [MIT license](LICENSE).