Skip to content

Commit 38ef21e

Browse files
anandgupta42claude
anandgupta42
and
claude
authored
docs: port OpenCode platform docs to altimate-code (#27)
Move existing data engineering docs into data-engineering/ subdirectory and add 29 new pages covering platform features: TUI, CLI, web UI, IDE and CI/CD integration, configuration, providers, tools, agents, models, themes, keybinds, commands, formatters, permissions, LSP, MCP, ACP, skills, custom tools, SDK, server, plugins, ecosystem, network, troubleshooting, and Windows/WSL. All content adapted with altimate-code branding (env vars, config paths, package names). mkdocs builds with zero warnings. Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 01a453c commit 38ef21e

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

45 files changed

+2523
-15
lines changed

‎docs/docs/configure/acp.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# ACP Support
2+
3+
altimate-code implements the Agent Communication Protocol (ACP), allowing it to act as a backend for editors and IDEs.
4+
5+
## Usage
6+
7+
```bash
8+
altimate-code acp
9+
```
10+
11+
This starts altimate-code in ACP mode, ready to accept connections from compatible editors.
12+
13+
## Editor Configuration
14+
15+
### Zed
16+
17+
Add to your Zed settings:
18+
19+
```json
20+
{
21+
"language_models": {
22+
"altimate-code": {
23+
"command": ["altimate-code", "acp"]
24+
}
25+
}
26+
}
27+
```
28+
29+
### JetBrains IDEs
30+
31+
Configure altimate-code as an external AI provider in your JetBrains IDE settings.
32+
33+
### Neovim
34+
35+
Use an ACP-compatible Neovim plugin to connect to altimate-code:
36+
37+
```lua
38+
require("acp").setup({
39+
command = { "altimate-code", "acp" }
40+
})
41+
```
42+
43+
## Features
44+
45+
ACP mode provides:
46+
47+
- Model access through your configured providers
48+
- Tool execution (file operations, search, shell commands)
49+
- Agent selection and switching
50+
- Full data engineering tool access

‎docs/docs/configure/agents.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# Agents
2+
3+
Agents define different AI personas with specific models, prompts, permissions, and capabilities.
4+
5+
## Built-in Agents
6+
7+
### General Purpose
8+
9+
| Agent | Description |
10+
|-------|------------|
11+
| `general` | Default general-purpose coding agent |
12+
| `plan` | Planning agent — analyzes before acting |
13+
| `build` | Build-focused agent — prioritizes code generation |
14+
| `explore` | Read-only exploration agent |
15+
16+
### Data Engineering
17+
18+
| Agent | Description | Permissions |
19+
|-------|------------|------------|
20+
| `builder` | Create dbt models, SQL pipelines, transformations | Full read/write |
21+
| `analyst` | Explore data, run SELECT queries, generate insights | Read-only (enforced) |
22+
| `validator` | Data quality checks, schema validation, test coverage | Read + validate |
23+
| `migrator` | Cross-warehouse SQL translation and migration | Read/write for migration |
24+
25+
!!! tip
26+
Use the `analyst` agent when exploring data to ensure no accidental writes. Switch to `builder` when you are ready to create or modify models.
27+
28+
## Custom Agents
29+
30+
Define custom agents in `altimate-code.json`:
31+
32+
```json
33+
{
34+
"agent": {
35+
"reviewer": {
36+
"model": "anthropic/claude-sonnet-4-6",
37+
"prompt": "You are a data engineering code reviewer. Focus on SQL best practices, dbt conventions, and warehouse cost efficiency.",
38+
"description": "Reviews data engineering code",
39+
"permission": {
40+
"write": "deny",
41+
"edit": "deny",
42+
"bash": {
43+
"dbt docs generate": "allow",
44+
"*": "deny"
45+
}
46+
}
47+
}
48+
}
49+
}
50+
```
51+
52+
## Agent Configuration
53+
54+
| Field | Type | Description |
55+
|-------|------|-------------|
56+
| `model` | `string` | Model to use (`provider/model`) |
57+
| `variant` | `string` | Model variant |
58+
| `temperature` | `number` | Sampling temperature |
59+
| `top_p` | `number` | Nucleus sampling |
60+
| `prompt` | `string` | System prompt |
61+
| `description` | `string` | Agent description |
62+
| `disable` | `boolean` | Disable this agent |
63+
| `mode` | `string` | `"primary"`, `"subagent"`, or `"all"` |
64+
| `hidden` | `boolean` | Hide from agent list (subagents only) |
65+
| `color` | `string` | Hex color or theme color name |
66+
| `steps` | `number` | Max agentic iterations |
67+
| `permission` | `object` | Agent-specific permissions |
68+
| `options` | `object` | Custom options |
69+
70+
## Markdown Agent Definitions
71+
72+
Create agents as markdown files in `.altimate-code/agents/`:
73+
74+
```markdown
75+
---
76+
name: cost-reviewer
77+
model: anthropic/claude-sonnet-4-6
78+
description: Reviews queries for cost efficiency
79+
---
80+
81+
You are a Snowflake cost optimization expert. For every query:
82+
1. Estimate credit consumption
83+
2. Suggest warehouse size optimization
84+
3. Flag full table scans and cartesian joins
85+
4. Recommend clustering keys where appropriate
86+
```
87+
88+
!!! info
89+
Markdown agent files use YAML frontmatter for configuration and the body as the system prompt. This is a convenient way to define agents without editing your main config file.
90+
91+
## Agent Permissions
92+
93+
Each agent can have its own permission overrides that restrict or expand the default permissions:
94+
95+
```json
96+
{
97+
"agent": {
98+
"analyst": {
99+
"permission": {
100+
"write": "deny",
101+
"edit": "deny",
102+
"bash": {
103+
"dbt show *": "allow",
104+
"dbt list *": "allow",
105+
"*": "deny"
106+
}
107+
}
108+
}
109+
}
110+
}
111+
```
112+
113+
!!! warning
114+
Agent-specific permissions override global permissions. A `"deny"` at the agent level cannot be overridden by a global `"allow"`.
115+
116+
## Switching Agents
117+
118+
- **TUI**: Press leader + `a` or use `/agent <name>`
119+
- **CLI**: `altimate-code --agent analyst`
120+
- **In conversation**: Type `/agent validator`

‎docs/docs/configure/commands.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Commands
2+
3+
Custom commands let you define reusable slash commands.
4+
5+
## Creating Commands
6+
7+
Create markdown files in `.altimate-code/commands/`:
8+
9+
```
10+
.altimate-code/
11+
commands/
12+
review.md
13+
optimize.md
14+
test-coverage.md
15+
```
16+
17+
### Command Format
18+
19+
```markdown
20+
---
21+
name: review
22+
description: Review SQL for anti-patterns and best practices
23+
---
24+
25+
Review the following SQL file for:
26+
1. Anti-patterns (SELECT *, missing WHERE clauses, implicit joins)
27+
2. Cost efficiency (full table scans, unnecessary CTEs)
28+
3. dbt best practices (ref() usage, naming conventions)
29+
30+
File: $ARGUMENTS
31+
```
32+
33+
### Frontmatter Fields
34+
35+
| Field | Required | Description |
36+
|-------|----------|-------------|
37+
| `name` | Yes | Command name (used as `/name`) |
38+
| `description` | Yes | Description shown in command list |
39+
40+
### Variables
41+
42+
| Variable | Description |
43+
|----------|------------|
44+
| `$ARGUMENTS` | Everything typed after the command name |
45+
46+
## Using Commands
47+
48+
In the TUI:
49+
50+
```
51+
/review models/staging/stg_orders.sql
52+
/optimize warehouse queries
53+
```
54+
55+
## Discovery
56+
57+
Commands are loaded from:
58+
59+
1. `.altimate-code/commands/` in the project directory
60+
2. `~/.config/altimate-code/commands/` globally
61+
62+
Press leader + `/` to see all available commands.

‎docs/docs/configure/config.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# Configuration
2+
3+
altimate-code uses JSON (or JSONC) configuration files. The config file is named `altimate-code.json` or `altimate-code.jsonc`.
4+
5+
## Config File Locations
6+
7+
Configuration is loaded from multiple sources, with later sources overriding earlier ones:
8+
9+
| Priority | Source | Location |
10+
|----------|--------|----------|
11+
| 1 (lowest) | Remote defaults | `.well-known/altimate-code` (organization) |
12+
| 2 | Global config | `~/.config/altimate-code/altimate-code.json` |
13+
| 3 | Custom config | Path from `ALTIMATE_CLI_CONFIG` env var |
14+
| 4 | Project config | `altimate-code.json` (searched up directory tree) |
15+
| 5 | Directory config | `.altimate-code/altimate-code.json` (searched up tree) |
16+
| 6 | Inline config | `ALTIMATE_CLI_CONFIG_CONTENT` env var (JSON string) |
17+
| 7 (highest) | Managed config | `/Library/Application Support/altimate-code/` (macOS, enterprise) |
18+
19+
!!! tip
20+
For most projects, create a `altimate-code.json` in your project root or use the `.altimate-code/` directory for a cleaner setup.
21+
22+
## Minimal Example
23+
24+
```json
25+
{
26+
"provider": {
27+
"anthropic": {
28+
"apiKey": "{env:ANTHROPIC_API_KEY}"
29+
}
30+
},
31+
"model": "anthropic/claude-sonnet-4-6"
32+
}
33+
```
34+
35+
## Full Schema
36+
37+
| Field | Type | Description |
38+
|-------|------|-------------|
39+
| `$schema` | `string` | JSON schema URL for editor autocompletion |
40+
| `theme` | `string` | UI theme name |
41+
| `username` | `string` | Custom display username |
42+
| `model` | `string` | Default model (`provider/model`) |
43+
| `small_model` | `string` | Smaller model for lightweight tasks |
44+
| `default_agent` | `string` | Default agent to use on startup |
45+
| `logLevel` | `string` | Log level: `DEBUG`, `INFO`, `WARN`, `ERROR` |
46+
| `share` | `string` | Session sharing: `"manual"`, `"auto"`, `"disabled"` |
47+
| `autoupdate` | `boolean \| "notify"` | Auto-update behavior |
48+
| `provider` | `object` | Provider configurations (see [Providers](providers.md)) |
49+
| `mcp` | `object` | MCP server configurations (see [MCP Servers](mcp-servers.md)) |
50+
| `formatter` | `object \| false` | Formatter settings (see [Formatters](formatters.md)) |
51+
| `lsp` | `object \| false` | LSP server settings (see [LSP Servers](lsp.md)) |
52+
| `permission` | `object` | Permission rules (see [Permissions](permissions.md)) |
53+
| `agent` | `object` | Agent definitions (see [Agents](agents.md)) |
54+
| `keybinds` | `object` | Keybinding overrides (see [Keybinds](keybinds.md)) |
55+
| `tui` | `object` | TUI settings |
56+
| `server` | `object` | Server settings |
57+
| `skills` | `object` | Skill paths and URLs |
58+
| `plugin` | `string[]` | Plugin specifiers |
59+
| `instructions` | `string[]` | Glob patterns for instruction files |
60+
| `compaction` | `object` | Context compaction settings |
61+
| `experimental` | `object` | Experimental feature flags |
62+
63+
## Value Substitution
64+
65+
Config values support dynamic substitution so you never need to hardcode secrets.
66+
67+
### Environment Variables
68+
69+
Use `{env:VAR_NAME}` to inject environment variables:
70+
71+
```json
72+
{
73+
"provider": {
74+
"anthropic": {
75+
"apiKey": "{env:ANTHROPIC_API_KEY}"
76+
}
77+
}
78+
}
79+
```
80+
81+
### File Contents
82+
83+
Use `{file:path}` to read a secret from a file:
84+
85+
```json
86+
{
87+
"provider": {
88+
"anthropic": {
89+
"apiKey": "{file:~/.secrets/anthropic-key}"
90+
}
91+
}
92+
}
93+
```
94+
95+
!!! warning
96+
Never commit plaintext API keys to version control. Always use `{env:...}` or `{file:...}` substitution.
97+
98+
## Project Structure
99+
100+
A typical project layout using the `.altimate-code/` directory:
101+
102+
```
103+
my-project/
104+
.altimate-code/
105+
altimate-code.json # Project config
106+
agents/ # Custom agent definitions
107+
commands/ # Custom slash commands
108+
plugins/ # Custom plugins
109+
tools/ # Custom tools
110+
skill/ # Custom skills
111+
altimate-code.json # Alternative project config location
112+
```
113+
114+
## Compaction Settings
115+
116+
Control how context is managed when conversations grow long:
117+
118+
```json
119+
{
120+
"compaction": {
121+
"auto": true,
122+
"prune": true,
123+
"reserved": 4096
124+
}
125+
}
126+
```
127+
128+
| Field | Default | Description |
129+
|-------|---------|-------------|
130+
| `auto` | `true` | Auto-compact when context is full |
131+
| `prune` | `true` | Prune old tool outputs |
132+
| `reserved` | — | Token buffer to reserve |
133+
134+
!!! info
135+
Compaction automatically summarizes older messages to free up context window space, allowing longer conversations without losing important context.

0 commit comments

Comments
 (0)