Skip to content

getting-started.md

Latest commit

 

History

History
283 lines (194 loc) · 9.03 KB

getting-started.md

File metadata and controls

283 lines (194 loc) · 9.03 KB
Raw

Getting Started with LLxprt Code

This guide walks you through your first session — from installation to your first AI-assisted coding task.

Prerequisites

  • Node.js 24+ installed on your system (not required for Homebrew)
  • A terminal/command line

Note: LLxprt Code runs on the Bun runtime under the covers. Node.js remains the compatibility target for invocation — the npm/npx/Homebrew install commands below work unchanged. The published package bundles Bun as a dependency, so most users never need to install Bun separately.

Install LLxprt Code

npm install -g @vybestack/llxprt-code

Or run without installing:

npx @vybestack/llxprt-code

Bun Runtime and Install Fallback

LLxprt Code is powered by the Bun runtime. When you run llxprt, a platform-native launcher resolves the package-local Bun and execs the CLI under it. The launcher executes the TypeScript (.ts) entry point directly — the CLI's run path does not require a pre-compiled dist/ artifact. No Node process is started on the installed command path, and Bun does not need to be on your PATH.

Bun resolution order (production launcher):

  1. Package-local: <package>/node_modules/bun/bin/bun.exe (the package's pinned bun dependency)
  2. Hoisted (installed packages only): the enclosing node_modules/bun/bin/bun.exe (npm/Bun hoisting), stopping at the enclosing node_modules boundary — never climbing into consumer ancestors
  3. Workspace root (source workspace only): when the package is not under a node_modules and the repository root is a verified llxprt-code workspace, that verified root's node_modules/bun/bin/bun.exe

The launcher never scans .bin symlinks and never falls back to a global bun on PATH, so a separately installed Bun is not required. When an exact Bun pin is declared, a candidate whose version is missing or mismatched is rejected. If no package-local Bun is found, the launcher prints an error with instructions:

LLxprt Code: bundled Bun runtime was not found. Reinstall the package with "npm install @vybestack/llxprt-code" to restore the bundled Bun dependency, or visit https://bun.sh

To resolve this:

  • npm users: Re-run npm install @vybestack/llxprt-code (or npm install -g @vybestack/llxprt-code) to restore the bundled Bun dependency.
  • Homebrew users: Run brew upgrade llxprt-code to get the latest formula, or brew reinstall llxprt-code to restore a broken installation.
  • All users: If the bundled Bun dependency cannot be restored, reinstalling the package is the supported path. A separately installed global Bun is not used by the launcher.

Choose Your Path

LLxprt Code works with multiple AI providers. Pick the option that works for you:

Option A: Free & Low-Cost Tiers

Note: Google removed the free "Login with Google" flow for Gemini CLI in mid-2026; use a Gemini API key or Vertex AI instead. Qwen's free OAuth tier ended 2026-04-15 — use a DashScope API key instead. See authentication for current details.

Gemini (Google) — API key or Vertex AI:

llxprt
/key save gemini your-gemini-api-key
/provider gemini
/model gemini-2.5-flash

Qwen (Alibaba) — for coding tasks (API key via DashScope):

llxprt
/provider qwen
/key save qwen your-dashscope-key
/key load qwen
/model qwen3-coder-plus

Option B: Use Your Existing Subscription (OAuth)

If you already pay for Claude or OpenAI, use your subscription directly — no separate API billing:

Claude Pro/Max ($20–200/month):

llxprt
/auth anthropic enable
/provider anthropic
/model claude-opus-4-8

OpenAI ChatGPT Plus/Pro:

llxprt
/auth codex enable
/provider codex
/model gpt-5.6-sol

Each /auth <provider> enable command enables lazy OAuth — a browser opens automatically when you make your first request to that provider. Use /auth <provider> login to open the browser immediately.

Option C: API Keys

For direct API access, use /key save to store your key in your system keyring. You only need to do this once — afterwards, /key load retrieves it without exposing the key in your shell history or to the LLM. Keys are automatically masked when you paste them into the REPL.

Anthropic:

llxprt
/key save anthropic sk-ant-***your-key***
/provider anthropic
/key load anthropic
/model claude-opus-4-8

OpenAI:

llxprt
/key save openai sk-***your-key***
/provider openai
/key load openai
/model gpt-5.5

Open-weight models — providers like Synthetic, Z.ai, Chutes, Kimi.com, and Deepseek.ai give you access to models like DeepSeek, Kimi, Minimax, GLM, and Qwen:

Synthetic:

llxprt
/key save synthetic syn-***your-key***
/provider Synthetic
/key load synthetic
/model hf:Qwen/Qwen3-Coder

Z.ai:

llxprt
/key save zai zai-***your-key***
/provider zai
/key load zai
/model glm-5

After saving a key once, you only need /key load <name> in future sessions.

Your First Session

1. Navigate to Your Project

cd your-project-directory
llxprt

LLxprt Code automatically reads your project context.

2. Ask a Question

Type naturally at the prompt:

> Explain the structure of this codebase

The AI analyzes your project files and explains the architecture.

3. Try a File Operation

LLxprt Code can read and modify files with your approval:

> Read the README.md file and suggest improvements

Or create new files:

> Create a simple unit test for the main module

LLxprt Code asks for confirmation before writing files. Review changes before accepting.

4. Debug an Issue

Paste an error message directly:

> I'm getting this error: TypeError: Cannot read property 'map' of undefined
  at UserList.render (src/components/UserList.js:24)
  Help me fix it

5. Save Your Configuration

Once you have your provider and model configured, save it as a profile so you don't have to set it up again:

/profile save model my-setup

Load it anytime:

/profile load my-setup

Or set it as your default:

/profile set-default my-setup

Essential Commands

Command Description
/help Show all available commands
/provider Switch AI provider
/model Change the AI model
/auth <provider> enable Set up OAuth authentication
/key save <name> <key> Save an API key to your keyring
/key load <name> Load a saved API key
/profile save model <name> Save your current configuration
/profile load <name> Load a saved profile
/stats quota Check your current quota usage
/clear Clear conversation history
/quit or Ctrl+C Exit LLxprt Code

Tips for Better Results

  1. Be specific — "Add error handling to the login function in src/auth.js" works better than "improve my code"
  2. Provide context — Mention relevant files, error messages, or constraints
  3. Iterate — Follow up with clarifications or ask for alternatives
  4. Use the right model — Larger models (claude-opus-4-8, gpt-5.5) for complex tasks, faster models (gemini-2.5-flash, claude-haiku-4-5) for quick questions
  5. Think bigger for bigger projects — This guide gets you started with quick tasks, but for larger projects you should have distinct requirements, planning, and execution phases. Check out the Beyond Vibe Coding YouTube series for how to approach real-world autonomous development workflows

Security Tip: Sandboxing

When working with code from external sources, enable sandboxing to protect your system:

llxprt --sandbox-profile-load safe "review this pull request"

Sandboxing isolates tool execution from your host using Docker or Podman containers. Credentials stay on the host through the credential proxy, and host access is limited to explicit mounts used by the sandbox runtime.

For a full walkthrough, see the Sandbox Tutorial.

Next Steps

Now that you're up and running:

  • Profiles — Save and manage multiple configurations
  • Subagents — Create specialized AI assistants for different tasks
  • Local Models — Run models locally for complete privacy
  • Sandboxing — Protect your system with container isolation

Troubleshooting

Authentication Issues

/auth <provider> status
/auth <provider> logout
/auth <provider> enable

Model Not Available

/model
/provider

Quota Issues

Check your current usage and limits:

/stats quota

Need More Help?