Light-Agent

GitHub

Light-Agent is a minimal, local-first coding agent tuned for practical coding work with small local models.

What Changed

Light-Agent keeps the useful inherited runtime scaffolding while defaulting to a smaller local model workflow:

• Light-Agent has one default runtime profile tuned for small local models.
• The model sees a smaller tool surface by default: file read, file write, append, patch, bash, search, and file finding.
• MCP, plugins, skills, graph, memory, web browsing, and cloud escalation are hidden or disabled unless explicitly enabled.
• Sessions, traces, snapshots, memory, and tool scores are stored in a Light-Agent state directory instead of task workspaces by default.
• Exact verification instructions are stronger: if a task asks for exact output or exact file content, Light-Agent should verify that exact evidence before claiming success.
• Windows Python commands fall back from python to py, then to Codex's bundled Python runtime when present.
• A local benchmark command is included so changes can be measured repeatedly.

Install

Use Node.js 18 or newer.

Run the latest npm package:

npx light-agent@latest

Package links:

• npm: https://www.npmjs.com/package/light-agent
• GitHub: https://github.com/noobezlol/lightagent

For a local checkout:

cd D:\lightagent
npm install

Install or start Ollama, then pull the recommended small local model:

ollama pull qwen3.5:4b
ollama serve

Ollama's OpenAI-compatible endpoint is usually:

http://localhost:11434/v1

Configure

Light-Agent accepts LIGHT_AGENT_* environment variables.

$env:LIGHT_AGENT_MODEL = "qwen3.5:4b"
$env:LIGHT_AGENT_BASE_URL = "http://localhost:11434/v1"
$env:LIGHT_AGENT_PROVIDER = "openai"
$env:LIGHT_AGENT_AUTO_COMMIT = "false"

You can also copy .env.example to .env.

If no model is configured, Light-Agent exits with a setup error instead of silently using a cloud model.

Default Tool Policy

Light-Agent exposes only the core local tools to the model by default:

• read_file
• write_file
• append_file
• patch
• bash
• search
• find_files

Optional inherited systems are still in the codebase, but hidden by default. Enable them only when needed:

$env:LIGHT_AGENT_ENABLE_GRAPH = "true"
$env:LIGHT_AGENT_ENABLE_MEMORY = "true"
$env:LIGHT_AGENT_ENABLE_MCP = "true"
$env:LIGHT_AGENT_ENABLE_PLUGINS = "true"
$env:LIGHT_AGENT_ENABLE_SKILLS = "true"
$env:LIGHT_AGENT_WEB_BROWSE = "true"

Cloud escalation remains off unless LIGHT_AGENT_ESCALATION=true.

Runtime State

Light-Agent avoids creating .light-agent, .memory, traces, sessions, or snapshots inside ordinary task workspaces by default.

State is stored in this order:

1. LIGHT_AGENT_STATE_DIR if set.
2. <workspace>\.lightagent-state only when LIGHT_AGENT_WORKSPACE_STATE=true.
3. D:\lightagent\.lightagent-state when running from this repo.
4. %LOCALAPPDATA%\light-agent for other Windows workspaces.

Usage

Interactive:

npm start

The interactive UI uses the full-screen terminal layout and starts in /chat mode. Chat mode is read-only: it can answer questions and use read-only workspace tools, but it cannot edit files or run commands. Use /agent when you want the full agent workflow with writes, patches, shell commands, and verification. For CI, pipes, or terminals without raw-mode support, use --prompt or --non-interactive instead.

Useful interactive commands:

• /chat: switch to read-only chat mode.
• /agent: switch to full workspace action mode.
• /status: interaction mode, tool class, model, provider, cwd, state dir, changed files, and verification state.
• /files: files read and changed during the session.
• /diff: readable changed-file diff preview.
• /verify: last verification status.
• /log: trace, session, snapshot, and state locations.
• /undo: rollback support when available.

Non-interactive:

node bin/light-agent.js --prompt "Create hello.txt containing Hello, friend!"

Non-interactive --prompt keeps the existing agent workflow by default so benchmarks and automation can still edit, run, and verify without entering /agent first.

Preferred command name after global install or npm link:

npx light-agent@latest --prompt "Read package.json and summarize the scripts"

The package exposes light-agent, lagent, and node bin/light-agent.js. Old upstream command aliases are not part of the runtime.

Local Benchmark

Run the built-in three-task benchmark:

npm run bench:local

It creates isolated workspaces under the Light-Agent state directory and scores 18 points:

• Create hello.txt containing exactly Hello, friend!.
• Edit greet.py after reading it, then verify it prints exactly Hello, Light-Agent.
• Create calculator.py with arithmetic functions and a CLI where python calculator.py add 2 3 prints exactly 5.

The benchmark does not run as part of npm test. It uses LIGHT_AGENT_MODEL when set, otherwise qwen3.5:4b, and reports failures honestly.

Run the extended local correctness benchmark:

npm run bench:local:extended

The extended suite scores 35 points across exact JSON creation, modify-only edits, CLI argument handling, README preservation, and Node export-plus-CLI behavior.

Architecture

The current codebase is still close to the inherited upstream runtime:

• bin/light-agent.js: CLI entrypoint, argument parsing, TUI boot, non-interactive mode, and the main agent loop.
• bin/config.js: model, provider, base URL, feature flags, and state config.
• bin/model_client.js: OpenAI-compatible chat calls, streaming, validation, and model response handling.
• bin/tools.js: model-facing tool schemas and the default tool policy.
• bin/executor.js: tool execution, read-before-edit guard, patch/write/bash behavior, and Windows Python fallback.
• src/runtime/state_dir.js: Light-Agent state directory selection.
• src/runtime/exact_verifier.js: lightweight exact-output/content verification guard.
• src/session/: sessions, snapshots, file-state tracking, references, planning, bootstrap, and git context.
• src/tools/: shell persistence, read tracking, test-runner discovery, tool routing, MCP client, and web browsing support.
• src/plugins/ and skills/: inherited plugin and skill loading.
• bench/: upstream benchmark harness retained for future comparison work.

Safety And Limits

Light-Agent is a local coding agent, not a security boundary.

• It can read, create, edit, and run files in the workspace it is pointed at.
• Review changes before committing.
• Keep auto-commit disabled unless you explicitly want it.
• Web browsing, MCP, plugins, skills, graph, memory, and cloud escalation are disabled by default because they add confusion for small local models.
• Snapshots and traces help recovery and debugging, but they do not replace backups.
• Exact verification is intentionally lightweight. It improves obvious exact-output and exact-content cases, but it is not a full requirements parser.

What Is Still Inherited

This fork keeps inherited optional systems available for future work:

• MCP client/server support.
• Plugin and skill loading.
• Code graph, memory, sessions, snapshots, and traces.
• BoneScript helpers and compiled cognition modules.
• Web tools, gated by environment flags.
• Upstream benchmark harnesses and planning documents.

Future Light-Agent passes can remove or simplify these once tests cover the desired minimal surface.

License

Light-Agent is licensed under MIT.