@kmugalkhod/lightcode 0.7.0 → 0.7.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.
- package/README.md +119 -119
- package/cli.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,119 +1,119 @@
|
|
|
1
|
-
# Lightcode
|
|
2
|
-
|
|
3
|
-
A personal AI coding agent with a terminal UI. Lightcode pairs an OpenTUI
|
|
4
|
-
chat interface with a local Hono API server, persistent SQLite sessions, a
|
|
5
|
-
permission-gated tool suite (files, shell, git, web, MCP), and tiered context
|
|
6
|
-
optimization that keeps long sessions inside the model's context window
|
|
7
|
-
without ever losing history.
|
|
8
|
-
|
|
9
|
-
## Install
|
|
10
|
-
|
|
11
|
-
```bash
|
|
12
|
-
npm install -g @kmugalkhod/lightcode
|
|
13
|
-
lightcode
|
|
14
|
-
```
|
|
15
|
-
|
|
16
|
-
Works on macOS (Apple Silicon and Intel), Linux, and Windows. Bun ships with
|
|
17
|
-
the package, so there's nothing else to install — the first `lightcode` run
|
|
18
|
-
uses the bundled runtime automatically (and reuses a system Bun if you already
|
|
19
|
-
have one). The published package is scoped as `@kmugalkhod/lightcode`; the
|
|
20
|
-
command it installs is `lightcode`.
|
|
21
|
-
|
|
22
|
-
## Quick start (from source)
|
|
23
|
-
|
|
24
|
-
```bash
|
|
25
|
-
bun install
|
|
26
|
-
bun run cli:dev # starts the TUI; it boots the server automatically
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
Lightcode is aware of the directory you launch it in: each turn it reads the
|
|
30
|
-
project's shape (top-level files, git branch/status) and any `AGENTS.md` /
|
|
31
|
-
`CLAUDE.md` / `README.md`, so "review my code" or "explain this" inspects your
|
|
32
|
-
actual files instead of asking you to paste them.
|
|
33
|
-
|
|
34
|
-
On first run Lightcode walks you through provider setup (Anthropic,
|
|
35
|
-
OpenRouter, OpenCode Zen, or any OpenAI-compatible endpoint) and stores the
|
|
36
|
-
API key in `~/.lightcode/credentials.json`. Environment variables such as
|
|
37
|
-
`ANTHROPIC_API_KEY` always take precedence.
|
|
38
|
-
|
|
39
|
-
## Commands
|
|
40
|
-
|
|
41
|
-
```bash
|
|
42
|
-
bun run cli:dev # TUI (auto-starts the server)
|
|
43
|
-
bun run server:dev # API server alone, watch mode
|
|
44
|
-
bun run typecheck # TypeScript + tool schema preflight
|
|
45
|
-
bun test # test suite
|
|
46
|
-
bun run build # build the publishable package into dist/
|
|
47
|
-
bun run release # verify + build + npm pack (--publish to release)
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
## Configuration
|
|
51
|
-
|
|
52
|
-
Settings merge from `~/.lightcode/settings.json`, then
|
|
53
|
-
`.lightcode/settings.json` in the project, then `LIGHTCODE_*` environment
|
|
54
|
-
variables. Notable keys:
|
|
55
|
-
|
|
56
|
-
| Key | Purpose |
|
|
57
|
-
| --- | --- |
|
|
58
|
-
| `provider`, `model`, `baseUrl` | Provider selection and model id |
|
|
59
|
-
| `defaultMode` | `build` or `plan` |
|
|
60
|
-
| `permissionMode`, `permissions` | Tool permission policy |
|
|
61
|
-
| `context.compactAtFraction` | Context compaction threshold (default 0.8) |
|
|
62
|
-
| `context.pruneAtFraction` | Tool-output pruning threshold (default 0.6) |
|
|
63
|
-
| `context.contextWindowOverride` | Override the model context window |
|
|
64
|
-
| `maxRetries` | Provider-call retries for transient errors (default 5) |
|
|
65
|
-
| `autoContinue.stallTimeoutSeconds` | Abort+retry a byte-silent stream (default 300; raise for very slow reasoning models) |
|
|
66
|
-
| `autoContinue.maxErrorRetries` | Auto-resends before surfacing a stream error (default 8) |
|
|
67
|
-
|
|
68
|
-
The local companion server listens on `127.0.0.1:4983` (uncommon on purpose —
|
|
69
|
-
port 3000 belongs to the apps you build). Override with `PORT` for the server
|
|
70
|
-
and `LIGHTCODE_API_URL` for the CLI. Runtime model switching: `/model` in the
|
|
71
|
-
TUI lists every OpenRouter model and persists the choice to
|
|
72
|
-
`~/.lightcode/settings.json`. Diagnostics: `GET /diagnostics/connectivity`
|
|
73
|
-
probes the provider endpoint, and daily JSONL logs live under the Lightcode
|
|
74
|
-
data directory (`logs/`).
|
|
75
|
-
|
|
76
|
-
## Context optimization
|
|
77
|
-
|
|
78
|
-
Long sessions stay healthy through three tiers: real-usage-calibrated token
|
|
79
|
-
estimation, free pruning of stale tool outputs and duplicate file reads, and
|
|
80
|
-
LLM-written summaries once the compaction threshold is crossed (with an
|
|
81
|
-
extractive fallback when the model is unreachable). The full conversation is
|
|
82
|
-
always preserved in SQLite — compaction only changes what the model sees.
|
|
83
|
-
Use `/compact` in a chat to compact manually.
|
|
84
|
-
|
|
85
|
-
## Skills
|
|
86
|
-
|
|
87
|
-
Skills are reusable instruction files the agent can load on demand — a recipe
|
|
88
|
-
for a recurring task (writing a PR description, cutting a release, following a
|
|
89
|
-
review checklist). Each skill is a `SKILL.md` file with frontmatter:
|
|
90
|
-
|
|
91
|
-
```markdown
|
|
92
|
-
---
|
|
93
|
-
name: pr-description
|
|
94
|
-
description: Write a clear PR title and description from the diff.
|
|
95
|
-
---
|
|
96
|
-
|
|
97
|
-
# Instructions the agent follows when this skill is loaded…
|
|
98
|
-
```
|
|
99
|
-
|
|
100
|
-
Lightcode discovers skills from three locations, first match wins (project
|
|
101
|
-
overrides user):
|
|
102
|
-
|
|
103
|
-
1. `.lightcode/skills/<name>/SKILL.md` — project-local
|
|
104
|
-
2. `.agents/skills/<name>/SKILL.md` — project-local (fallback)
|
|
105
|
-
3. `~/.lightcode/skills/<name>/SKILL.md` — available in every project
|
|
106
|
-
|
|
107
|
-
Each turn the agent is told which skills are available (name + description), so
|
|
108
|
-
just ask it to "use the pr-description skill" (or mention the skill by name) and
|
|
109
|
-
it loads the instructions via the `skill` tool and follows them. Run `/skills`
|
|
110
|
-
in the TUI to list what's installed. Only simple `key: value` frontmatter lines
|
|
111
|
-
are parsed (`name`, `description`); the rest of the file is the instruction body.
|
|
112
|
-
|
|
113
|
-
## Workspaces
|
|
114
|
-
|
|
115
|
-
- `apps/cli` — OpenTUI React terminal interface
|
|
116
|
-
- `apps/server` — Hono API server (sessions, streaming, diagnostics)
|
|
117
|
-
- `packages/ai` — agent core: tools, permissions, context engine, config
|
|
118
|
-
- `packages/db` — Prisma + local SQLite storage
|
|
119
|
-
- `packages/shared` — logging, errors, version
|
|
1
|
+
# Lightcode
|
|
2
|
+
|
|
3
|
+
A personal AI coding agent with a terminal UI. Lightcode pairs an OpenTUI
|
|
4
|
+
chat interface with a local Hono API server, persistent SQLite sessions, a
|
|
5
|
+
permission-gated tool suite (files, shell, git, web, MCP), and tiered context
|
|
6
|
+
optimization that keeps long sessions inside the model's context window
|
|
7
|
+
without ever losing history.
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npm install -g @kmugalkhod/lightcode
|
|
13
|
+
lightcode
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Works on macOS (Apple Silicon and Intel), Linux, and Windows. Bun ships with
|
|
17
|
+
the package, so there's nothing else to install — the first `lightcode` run
|
|
18
|
+
uses the bundled runtime automatically (and reuses a system Bun if you already
|
|
19
|
+
have one). The published package is scoped as `@kmugalkhod/lightcode`; the
|
|
20
|
+
command it installs is `lightcode`.
|
|
21
|
+
|
|
22
|
+
## Quick start (from source)
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
bun install
|
|
26
|
+
bun run cli:dev # starts the TUI; it boots the server automatically
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Lightcode is aware of the directory you launch it in: each turn it reads the
|
|
30
|
+
project's shape (top-level files, git branch/status) and any `AGENTS.md` /
|
|
31
|
+
`CLAUDE.md` / `README.md`, so "review my code" or "explain this" inspects your
|
|
32
|
+
actual files instead of asking you to paste them.
|
|
33
|
+
|
|
34
|
+
On first run Lightcode walks you through provider setup (Anthropic,
|
|
35
|
+
OpenRouter, OpenCode Zen, or any OpenAI-compatible endpoint) and stores the
|
|
36
|
+
API key in `~/.lightcode/credentials.json`. Environment variables such as
|
|
37
|
+
`ANTHROPIC_API_KEY` always take precedence.
|
|
38
|
+
|
|
39
|
+
## Commands
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
bun run cli:dev # TUI (auto-starts the server)
|
|
43
|
+
bun run server:dev # API server alone, watch mode
|
|
44
|
+
bun run typecheck # TypeScript + tool schema preflight
|
|
45
|
+
bun test # test suite
|
|
46
|
+
bun run build # build the publishable package into dist/
|
|
47
|
+
bun run release # verify + build + npm pack (--publish to release)
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## Configuration
|
|
51
|
+
|
|
52
|
+
Settings merge from `~/.lightcode/settings.json`, then
|
|
53
|
+
`.lightcode/settings.json` in the project, then `LIGHTCODE_*` environment
|
|
54
|
+
variables. Notable keys:
|
|
55
|
+
|
|
56
|
+
| Key | Purpose |
|
|
57
|
+
| --- | --- |
|
|
58
|
+
| `provider`, `model`, `baseUrl` | Provider selection and model id |
|
|
59
|
+
| `defaultMode` | `build` or `plan` |
|
|
60
|
+
| `permissionMode`, `permissions` | Tool permission policy |
|
|
61
|
+
| `context.compactAtFraction` | Context compaction threshold (default 0.8) |
|
|
62
|
+
| `context.pruneAtFraction` | Tool-output pruning threshold (default 0.6) |
|
|
63
|
+
| `context.contextWindowOverride` | Override the model context window |
|
|
64
|
+
| `maxRetries` | Provider-call retries for transient errors (default 5) |
|
|
65
|
+
| `autoContinue.stallTimeoutSeconds` | Abort+retry a byte-silent stream (default 300; raise for very slow reasoning models) |
|
|
66
|
+
| `autoContinue.maxErrorRetries` | Auto-resends before surfacing a stream error (default 8) |
|
|
67
|
+
|
|
68
|
+
The local companion server listens on `127.0.0.1:4983` (uncommon on purpose —
|
|
69
|
+
port 3000 belongs to the apps you build). Override with `PORT` for the server
|
|
70
|
+
and `LIGHTCODE_API_URL` for the CLI. Runtime model switching: `/model` in the
|
|
71
|
+
TUI lists every OpenRouter model and persists the choice to
|
|
72
|
+
`~/.lightcode/settings.json`. Diagnostics: `GET /diagnostics/connectivity`
|
|
73
|
+
probes the provider endpoint, and daily JSONL logs live under the Lightcode
|
|
74
|
+
data directory (`logs/`).
|
|
75
|
+
|
|
76
|
+
## Context optimization
|
|
77
|
+
|
|
78
|
+
Long sessions stay healthy through three tiers: real-usage-calibrated token
|
|
79
|
+
estimation, free pruning of stale tool outputs and duplicate file reads, and
|
|
80
|
+
LLM-written summaries once the compaction threshold is crossed (with an
|
|
81
|
+
extractive fallback when the model is unreachable). The full conversation is
|
|
82
|
+
always preserved in SQLite — compaction only changes what the model sees.
|
|
83
|
+
Use `/compact` in a chat to compact manually.
|
|
84
|
+
|
|
85
|
+
## Skills
|
|
86
|
+
|
|
87
|
+
Skills are reusable instruction files the agent can load on demand — a recipe
|
|
88
|
+
for a recurring task (writing a PR description, cutting a release, following a
|
|
89
|
+
review checklist). Each skill is a `SKILL.md` file with frontmatter:
|
|
90
|
+
|
|
91
|
+
```markdown
|
|
92
|
+
---
|
|
93
|
+
name: pr-description
|
|
94
|
+
description: Write a clear PR title and description from the diff.
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
# Instructions the agent follows when this skill is loaded…
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
Lightcode discovers skills from three locations, first match wins (project
|
|
101
|
+
overrides user):
|
|
102
|
+
|
|
103
|
+
1. `.lightcode/skills/<name>/SKILL.md` — project-local
|
|
104
|
+
2. `.agents/skills/<name>/SKILL.md` — project-local (fallback)
|
|
105
|
+
3. `~/.lightcode/skills/<name>/SKILL.md` — available in every project
|
|
106
|
+
|
|
107
|
+
Each turn the agent is told which skills are available (name + description), so
|
|
108
|
+
just ask it to "use the pr-description skill" (or mention the skill by name) and
|
|
109
|
+
it loads the instructions via the `skill` tool and follows them. Run `/skills`
|
|
110
|
+
in the TUI to list what's installed. Only simple `key: value` frontmatter lines
|
|
111
|
+
are parsed (`name`, `description`); the rest of the file is the instruction body.
|
|
112
|
+
|
|
113
|
+
## Workspaces
|
|
114
|
+
|
|
115
|
+
- `apps/cli` — OpenTUI React terminal interface
|
|
116
|
+
- `apps/server` — Hono API server (sessions, streaming, diagnostics)
|
|
117
|
+
- `packages/ai` — agent core: tools, permissions, context engine, config
|
|
118
|
+
- `packages/db` — Prisma + local SQLite storage
|
|
119
|
+
- `packages/shared` — logging, errors, version
|
package/cli.js
CHANGED