Skip to content

Commit 047c30e

Browse files
tj-doomer-ittj-doomer-it
committed
docs: rewrite README to reflect the actual product
Covers provider registry, mid-session switching, 20+ tools, personas, diagnostics, and supported providers. Removes the old env-var-only setup in favor of /model add workflow.
1 parent 991ba3e commit 047c30e

1 file changed

Lines changed: 124 additions & 88 deletions

File tree

‎README.md‎

Lines changed: 124 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -1,135 +1,171 @@
11
# Delta Code
22

3-
![Delta Code Screenshot](./docs/assets/Delta-screenshot.png)
3+
AI-powered coding agent for the terminal. Any model. Every tool. Zero lock-in.
44

5-
AI-powered CLI for developers, adapted from Gemini CLI and optimized for use with any foundation model.
5+
Delta Code connects to any LLM provider — local models via LM Studio/Ollama, OpenAI, Anthropic, Google, Azure, or any OpenAI-compatible endpoint — and gives the model a rich set of coding tools: file editing, search, shell execution, linting, testing, codebase navigation, and more.
6+
7+
Switch providers mid-conversation. Plan with a cloud model, implement with a local one. Your context carries over.
68

79
## Install
810

9-
Requires Node.js ≥ 20.
11+
Requires Node.js >= 20.
1012

1113
```bash
12-
# Clone and enter the repo (your fork)
1314
git clone https://github.com/tjdoomer/Delta-code.git
1415
cd Delta-code
15-
16-
# Build
17-
npm ci
18-
npm run build
19-
20-
# Install the CLI globally
16+
npm ci && npm run build
2117
npm install -g .
22-
delta
2318
```
2419

25-
## Quick start
20+
## Quick Start
2621

2722
```bash
23+
# First run — add your provider
2824
delta
29-
```
25+
> /model add lmstudio openai-compatible http://localhost:1234/v1
3026

31-
## Authentication
27+
# Every run after — auto-connects to your saved provider
28+
delta
29+
```
3230

33-
You can authenticate in two ways:
31+
Or use environment variables:
3432

35-
- Interactive (recommended): run `delta`, pick a provider from the menu, and follow the prompts. If a required key is missing, the CLI will ask for it and store it in the current process environment.
36-
- Environment variables: define the variables below (e.g., in a `.env` file) and run `delta`. The CLI will detect them and skip the prompts.
33+
```bash
34+
OPENAI_API_KEY="lm-studio" OPENAI_BASE_URL="http://localhost:1234/v1" delta
35+
```
3736

38-
### OpenAI
37+
## Provider Registry
3938

40-
- Best path: choose “OpenAI” in the menu and paste your API key (and optionally a custom base URL/model).
41-
- Environment variables:
39+
Save connections once, switch between them anytime. Credentials persist in `~/.delta/providers.json`.
4240

4341
```bash
44-
OPENAI_API_KEY="sk-..."
45-
# Optional if using a custom endpoint
46-
OPENAI_BASE_URL="https://api.openai.com/v1"
47-
# Optional; set a default model name for your workflow
48-
OPENAI_MODEL="gpt-4o-mini"
49-
```
42+
# Add connections
43+
/model add lmstudio openai-compatible http://localhost:1234/v1
44+
/model add ollama openai-compatible http://localhost:11434/v1
45+
/model add openai openai https://api.openai.com/v1 sk-your-key
46+
/model add anthropic anthropic https://api.anthropic.com/v1 sk-ant-your-key
5047

51-
### Google (Gemini API key)
48+
# Discover local models
49+
/model refresh
5250

53-
- Best path: choose “Google (Gemini API key)” and paste your Google AI Studio key.
54-
- Environment variables:
51+
# List everything
52+
/model list
5553

56-
```bash
57-
GEMINI_API_KEY="your-google-ai-studio-key"
54+
# Switch provider mid-conversation (history preserved)
55+
/switch lmstudio
56+
/switch anthropic
5857
```
5958

60-
### Azure OpenAI
61-
62-
- Best path: choose “Azure OpenAI” and paste:
63-
- API Key
64-
- Full base URL to your deployment’s chat completions endpoint
65-
- Deployment name (used as the model id)
66-
- Environment variables (what the CLI sets under the hood):
59+
## Tools
60+
61+
Delta ships with 20+ tools the model can invoke:
62+
63+
| Tool | What it does |
64+
|------|-------------|
65+
| `read_file` | Read file contents with pagination |
66+
| `write_file` | Create or overwrite files |
67+
| `replace` | Precise text replacement with context matching |
68+
| `multi_edit` | Atomic edits across multiple files |
69+
| `diff_preview` | Preview an edit as a unified diff before applying |
70+
| `glob` | Find files by pattern |
71+
| `search_file_content` | Regex search across the codebase |
72+
| `read_file_summary` | Structural skeleton — signatures only, ~95% fewer tokens |
73+
| `repo_map` | Ranked codebase map with dependency graph and PageRank |
74+
| `run_shell_command` | Execute shell commands |
75+
| `lint` | Auto-detect and run project linter with structured output |
76+
| `run_tests` | Auto-detect and run project tests |
77+
| `think` | Structured reasoning before acting (no side effects) |
78+
| `checkpoint_save` | Save workspace state before risky changes |
79+
| `checkpoint_restore` | Revert to a saved checkpoint |
80+
| `checkpoint_list` | List saved checkpoints |
81+
| `save_memory` | Persist facts across sessions |
82+
| `todo_write` | Track tasks within a session |
83+
| `web_search` | Search the web (requires Tavily API key) |
84+
| `web_fetch` | Fetch and parse URL content |
85+
| `sub_agent` | Spawn autonomous sub-agents for complex tasks |
86+
87+
## Commands
88+
89+
| Command | What it does |
90+
|---------|-------------|
91+
| `/model list` | Show all available models across connections |
92+
| `/model set <name>` | Change the active model |
93+
| `/model add` | Save a new provider connection |
94+
| `/model refresh` | Re-discover models from local servers |
95+
| `/switch <id>` | Swap provider mid-conversation |
96+
| `/doctor` | Provider health check — env vars, connectivity, model |
97+
| `/persona set <id>` | Change writing style (see Personas below) |
98+
| `/checkpoint save` | Save a workspace checkpoint |
99+
| `/checkpoint restore` | Restore a checkpoint |
100+
| `/chat save` | Save conversation |
101+
| `/chat list` | List saved conversations |
102+
| `/theme` | Change color theme |
103+
| `/help` | Show all commands |
104+
105+
## Personas
106+
107+
Easter egg — change Delta's personality without affecting technical capability.
67108

68109
```bash
69-
OPENAI_API_KEY="your-azure-openai-key"
70-
OPENAI_BASE_URL="https://{resource}.openai.azure.com/openai/deployments/{deployment}/chat/completions?api-version=2024-08-01-preview"
71-
OPENAI_MODEL="{deployment}"
110+
/persona list # Show all personas
111+
/persona set noir # Hardboiled detective investigating bugs
112+
/persona set salaryman # Dedicated Japanese office worker
113+
/persona set 1950s # Mid-century company man
114+
/persona set pirate # Seafaring programmer
115+
/persona set shakespeare # The Bard writes your pull requests
116+
/persona set drill-sergeant # WILL NOT tolerate sloppy code
117+
/persona set corporate # Synergize the codebase
118+
/persona set default # Back to normal
72119
```
73120

74-
### AWS Bedrock (Claude)
121+
Custom personas: drop a `.md` file in `~/.delta/personas/` — filename becomes the ID, content becomes the voice.
75122

76-
- Best path: choose “AWS Bedrock (Claude)” and enter:
77-
- Access Key ID (as the API Key field)
78-
- Secret Access Key (as the Base URL field)
79-
- Region (as the Model field)
80-
- Environment variables:
123+
## Diagnostics
81124

82125
```bash
83-
AWS_ACCESS_KEY_ID="AKIA..."
84-
AWS_SECRET_ACCESS_KEY="..."
85-
AWS_REGION="us-east-1"
126+
/doctor
86127
```
87128

88-
### Claude (Anthropic)
129+
Validates your setup: API keys (detects placeholders), local server reachability (LM Studio, Ollama), saved connection health, and active model configuration.
89130

90-
- Best path: choose "Claude", paste your Anthropic API key, and select from available models (Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4, Claude 3.7 Sonnet, Claude 3.5 Sonnet).
91-
- Environment variables:
131+
## Supported Providers
92132

93-
```bash
94-
ANTHROPIC_API_KEY="your-anthropic-key"
95-
# Optional: specify a default model
96-
CLAUDE_MODEL="claude-opus-4-1-20250805"
97-
```
133+
| Provider | Connection Type | Local |
134+
|----------|----------------|-------|
135+
| LM Studio | `openai-compatible` | Yes |
136+
| Ollama | `openai-compatible` | Yes |
137+
| OpenAI | `openai` | No |
138+
| Anthropic Claude | `anthropic` | No |
139+
| Google Gemini | `gemini` | No |
140+
| Azure OpenAI | `openai-compatible` | No |
141+
| AWS Bedrock | `openai-compatible` | No |
142+
| Any OpenAI-compatible | `openai-compatible` | Depends |
98143

99-
### Using a .env file
144+
## Architecture
100145

101-
Place a `.env` file in your working directory and add the variables for the provider you use. Example with multiple providers configured (only the ones you use are required):
146+
Monorepo with npm workspaces:
102147

103-
```bash
104-
# OpenAI
105-
OPENAI_API_KEY=sk-...
106-
OPENAI_BASE_URL=https://api.openai.com/v1
107-
OPENAI_MODEL=gpt-4o-mini
108-
109-
# Google Gemini
110-
GEMINI_API_KEY=...
111-
112-
# Azure OpenAI
113-
# OPENAI_API_KEY=...
114-
# OPENAI_BASE_URL=https://{resource}.openai.azure.com/openai/deployments/{deployment}/chat/completions?api-version=2024-08-01-preview
115-
# OPENAI_MODEL={deployment}
116-
117-
# AWS Bedrock
118-
AWS_ACCESS_KEY_ID=...
119-
AWS_SECRET_ACCESS_KEY=...
120-
AWS_REGION=us-east-1
121-
122-
# Anthropic Claude
123-
ANTHROPIC_API_KEY=...
124-
CLAUDE_MODEL=claude-opus-4-1-20250805 # Optional: specify Claude model
125-
```
148+
- `packages/core` — content generators, tools, indexing, provider registry
149+
- `packages/cli` — Ink/React terminal UI, slash commands, auth flow
150+
- `packages/vscode-ide-companion` — VS Code extension
151+
152+
Key internals:
153+
- **Provider adapters** convert between a canonical type system and each provider's API (OpenAI, Anthropic, Google)
154+
- **Schema normalization** adapts tool declarations per-provider (strict mode for OpenAI, permissive for Gemini)
155+
- **Repo indexing** uses regex-based symbol extraction, import dependency graph, and PageRank for codebase navigation
156+
- **Think block passthrough** surfaces reasoning traces from models like DeepSeek-R1, QwQ, Qwen3 instead of stripping them
126157

127158
## Docs
128159

129-
- Getting started and commands: ./docs/
130-
- Authentication details: ./docs/cli/authentication.md
131-
- Troubleshooting: ./docs/troubleshooting.md
160+
- [Commands](./docs/cli/commands.md)
161+
- [Authentication](./docs/cli/authentication.md)
162+
- [Configuration](./docs/cli/configuration.md)
163+
- [Tools](./docs/tools/index.md)
164+
- [Architecture](./docs/architecture.md)
165+
- [Troubleshooting](./docs/troubleshooting.md)
166+
167+
## License
132168

133-
## License & credits
169+
Apache-2.0. See [LICENSE](./LICENSE).
134170

135-
See ./LICENSE. Based on Google’s Gemini CLI with adaptations for Delta‑Coder models.
171+
Based on [Gemini CLI](https://github.com/google-gemini/gemini-cli) via [QwenLM/qwen-code](https://github.com/QwenLM/qwen-code).

0 commit comments

Comments
 (0)