Lexicon

Lexicon is a zero-dependency CLI inspired by the Codex developer experience. Instead of forcing you into a single AI vendor, Lexicon lets you drop in any HTTP-accessible completion/chat API (OpenAI-compatible by default) and ship code with the tooling you already know.

Requirements

• Node.js 18 or newer (for the built-in fetch implementation)

Installation

npm install
npm link   # exposes the `lexicon` command globally while developing

To remove the link later, run npm unlink -g lexicon.

Configuration

Run lexicon init once to scaffold a config file (defaults to ~/.lexicon/config.json). The generated JSON looks like this:

{
  "apiBaseUrl": "https://api.openai.com",
  "completionEndpoint": "/v1/chat/completions",
  "apiKey": "YOUR_API_KEY_HERE",
  "defaultModel": "gpt-4o-mini",
  "systemPrompt": "You are Lexicon, a helpful coding assistant.",
  "headers": {
    "Content-Type": "application/json"
  },
  "requestOptions": {
    "temperature": 0.2,
    "max_tokens": 4000,
    "timeout_ms": 60000
  }
}

Update the values to match your provider. Lexicon also reads the LEXICON_API_KEY environment variable, so you can skip storing secrets on disk.

Key fields:

• apiBaseUrl: Base URL to prepend to the completion endpoint (can be anything reachable inside your network).
• completionEndpoint: Path appended to the base URL (defaults to the OpenAI chat completions route).
• defaultModel: Model identifier to use when --model is not passed.
• headers: Static headers you want on every request (Lexicon automatically injects Authorization: Bearer <key> if missing).
• requestOptions: Additional properties merged into the JSON body on every request. You can override specific keys (temperature, max tokens, etc.) from the CLI.

Usage

Lexicon automatically injects context about the folder you run it from (workspace path, detected package/composer metadata, README excerpt, sample directories) into each request. You can still layer on more detail with --context or by piping files via --stdin.

Interactive chat

Run lexicon (or lexicon chat) to drop into a Codex-style chat loop that keeps the full conversation history:

lexicon
lexicon --model gpt-4o-mini --context "Working inside repo /srv/app"

While chatting you can use slash commands:

• /help – list the available commands.
• /exit or /quit – end the session.
• /clear – wipe the running conversation (retains the current system prompt/context).
• /system <prompt> – change the system prompt on the fly.
• Responses are wrapped in a banner that shows the active model, and the prompt line is colorized so it is easy to spot in long sessions.

File automation

Lexicon can apply file edits suggested by the assistant. Ask it to wrap content in fenced blocks using the file: or append: directives:

```file:src/index.js
console.log('hello from lexicon');
```

```append:README.md
New appendix content...
```

When those appear in a response, the CLI writes/append the content relative to the current working directory and lets you know what changed.

Safety heuristic: bare path fences (e.g., src/index.js) are only auto-applied if your prompt included intent words such as “write”, “create”, “update”, or “fix”. Explicit file:/append: directives skip that heuristic and always apply.

One-off prompts

Ask a single question inline (identical to Codex' default behavior):

lexicon "explain async hooks"
lexicon ask --model gpt-4o-mini "write a unit test for src/logger.js"
lexicon ask --file prompt.md --context "Project root: ~/repos/app" --timeout 45000

Override the API key temporarily:

LEXICON_API_KEY=abc123 lexicon "scaffold a remix loader"
# or
lexicon --key abc123 "document the build process"

Inspect the full JSON response:

lexicon ask "summarize this repo" --json

Feed input via STDIN:

git diff | lexicon ask --stdin "review these changes"

Common options

• --config <path>: Point to a different JSON config file.
• --model <id>: Override the configured model for a single run.
• --header "X-Org: dev": Append/override request headers (can pass multiple times).
• --temperature <number> / --maxTokens <number> / --timeout <ms>: Override request parameters.
• --json: Print the raw JSON response from your provider.
• --quiet: Suppress latency/usage summaries.

Run lexicon --help any time to view the complete reference.

Developing

• npm run dev runs the CLI directly from source.
• npm test currently prints the help output to make sure the CLI loads without syntax errors.

Feel free to extend the src/commands directory with more verbs (e.g., lexicon eval, lexicon history)—the CLI router auto-loads any command exported from there.