dimcode

dimcode

An AI coding agent for your terminal. Chat, run tasks, and automate development work from the command line.

dimcode is an AI coding agent CLI with an interactive terminal UI and a headless execution mode for one-off tasks.

Chinese

Installation

# beta channel (recommended for now)
npm i -g dimcode@beta

# or use bun / pnpm
bun add -g dimcode@beta
pnpm add -g dimcode@beta

The package installs two equivalent commands: dim and dimcode.

dim --version

During installation, npm automatically selects the matching platform binary package, such as dimcode-darwin-arm64 or dimcode-linux-x64. You do not need to choose one manually.

Supported Platforms

Platform	Binary package
macOS (Apple Silicon)	dimcode-darwin-arm64
macOS (Intel)	dimcode-darwin-x64
Linux (x64)	dimcode-linux-x64
Linux (ARM64)	dimcode-linux-arm64
Windows (x64)	dimcode-windows-x64

Quick Start

# Start the interactive terminal UI
dim

# Run a one-off task without opening the UI
dim exec "refactor the auth module to use JWT"

# Show the installed version
dim --version

# Show help
dim --help

On first launch, dimcode guides you through connecting a model provider such as OpenAI, Anthropic, or a custom endpoint.

Command Reference

Command	Description
dim	Start the interactive terminal UI (default)
dim exec "<prompt>"	Run a single prompt in headless mode
dim session list	List saved sessions
dim session rm <id>	Delete a saved session
dim provider list	Show configured model providers
dim provider add <id> --api-key <key>	Add a provider, such as openai
dim provider switch <id>	Switch the active provider
dim provider refresh-models	Refresh model lists from providers
dim mcp list	List MCP servers
dim auth login	Log in for cloud features
dim upgrade	Check for updates
dim --help	Show help
dim --version	Show the version

Interactive Terminal UI

Run dim to open the terminal UI:

+----------------------------------------------------------------------------+
| Session title   ~/workspace/repo                  12 messages | 42k | vdev |
+----------------------------------------------------------------------------+
|                                                                            |
| Conversation                                                               |
| - User messages                                                            |
| - Assistant replies                                                        |
| - Tool calls                                                               |
| - Reasoning                                                                |
|                                                                            |
+----------------------------------------------------------------------------+
| +------------------------------------------------------------------------+ |
| | Ask anything...                                                        | |
| | Agent mode  Ready                      42% context      ■ Model name    | |
| +------------------------------------------------------------------------+ |
+----------------------------------------------------------------------------+
| Select text      Clear input      Tab: switch mode    Ctrl+P: commands      |
+----------------------------------------------------------------------------+

The UI has four main areas:

• Header - session title, current directory, message count, token usage, and version
• Conversation - messages, assistant replies, tool output, and reasoning
• Composer - multiline input with image paste support
• Status bar - shortcuts and current state

Common Shortcuts

Shortcut	Action
Enter	Send message
Shift+Enter / Ctrl+J	Insert a newline
Tab	Switch between agent mode and plan mode
Ctrl+P	Open the command palette
Cmd+T (Mac) / Ctrl+T (other platforms)	Open the timeline
Cmd+N (Mac) / Ctrl+N (other platforms)	Create a new session / return home
/	Open and filter the command palette
@	Open the skill picker
Esc	Interrupt the current AI turn
Ctrl+C	Close modal -> clear input -> confirm exit
Ctrl+V	Paste an image from the clipboard
Up / Down	Browse input history when the composer is single-line

Slash Commands

Type / in the composer to open the command palette:

Command	Action
/new	Create a new session
/timeline	Show the current session timeline
/skills	Browse available skills
/resume	Open a saved session
/compact	Compact context to save tokens
/approvals	Adjust tool approval settings
/connect	Connect a model provider
/models	Switch models
/mcp	Manage MCP servers
/plugins	Show installed plugins
/theme	Switch theme
/settings	Open settings
/language	Change UI language
/exit	Exit

Runtime Prompts

While the agent is working, dimcode may ask for input:

• Tool approval - approve or deny a command or file access request with Y or N
• User question - answer a clarification question and the agent continues
• Exit confirmation - confirm before closing with Ctrl+C

Configuration

Configuration is stored under ~/.dimcode/ as a SQLite database and JSON files.

Add A Model Provider

# OpenAI
dim provider add openai --api-key sk-xxxxxxxx

# Custom local model endpoint
dim provider add mylocal --base-url http://127.0.0.1:11434 --model llama3

# Switch active provider
dim provider switch openai

# Refresh models
dim provider refresh-models openai

Environment Variables

Variable	Description
DIMCODE_LOG	Enable diagnostic logs under ~/.dimcode/logs/
DIMCODE_DEBUG	Print wrapper startup diagnostics for platform binary issues
DIMCODE_BIN_PATH	Use a custom binary path for development or debugging
NO_COLOR	Disable colored output
HTTPS_PROXY	Configure an HTTPS proxy

Headless Execution

Use dim exec for scripts and automation:

# Run one prompt directly
dim exec "write a Python script that sorts a CSV by column"

Exit Codes

Code	Meaning
0	Success
1	Runtime error
2	Argument error
3	Authentication failed

Upgrade And Uninstall

# Upgrade to the latest beta
npm i -g dimcode@beta

# Uninstall
npm uninstall -g dimcode

FAQ

Q: Installation succeeds, but the platform binary is missing.

npm may have skipped optional dependencies. Check with debug output first:

DIMCODE_DEBUG=1 dim --version

Then reinstall:

npm uninstall -g dimcode && npm i -g dimcode@beta

Q: The UI is blank or garbled.

Make sure your terminal supports 256 colors:

export TERM=xterm-256color

Q: How do I interrupt a running task?

Press Esc to interrupt the current AI turn.

Q: How do I send an image to the AI?

Paste an image from the clipboard with Ctrl+V, or paste an image path into the composer.

Q: Where is session data stored?

Local data lives under ~/.dimcode/v2/. Sessions are stored in the SQLite database dimcode.sqlite in tables such as sessions, session_states, session_relations, and session_blobs. Session data is not uploaded to the cloud.

The directory is roughly:

~/.dimcode/v2/
|-- config.json              global config
|-- providers.json           model providers
|-- auth.json                login state
|-- mcp.json                 MCP servers
|-- dimcode.sqlite           sessions / messages / state
|-- dimcode.sqlite-wal
|-- dimcode.sqlite-shm
|-- data/                    blob data
`-- logs/                    diagnostic logs

Q: How do I delete one session?

dim session list           # find the session id
dim session rm <id>

Q: How do I clear all session history?

The safest reset is to delete the SQLite database files while keeping config.json, providers.json, and other configuration:

rm -f ~/.dimcode/v2/dimcode.sqlite \
      ~/.dimcode/v2/dimcode.sqlite-wal \
      ~/.dimcode/v2/dimcode.sqlite-shm

To reset everything, including config, login state, and MCP servers, delete the whole v2 directory:

rm -rf ~/.dimcode/v2

Other directories under ~/.dimcode/, such as sessions/ and dimcode/, are leftovers from earlier versions and are not used by v2.

License

See the repository root LICENSE file.