Codeep

Deep into Code.

AI-powered coding assistant built for the terminal. Multiple LLM providers, project-aware context, and a seamless development workflow.

Features

$3

- Z.AI (ZhipuAI) - GLM-4.7, GLM-4.7 Flash models
- MiniMax - MiniMax M2.1 model
- Switch between providers with /provider
- Configure different API keys per provider

$3

When started in a project directory, Codeep automatically:
- Detects project type (Node.js, Python, etc.)
- Reads file paths mentioned in your messages
- Attaches file contents to conversations
- Understands your project structure
- Can suggest and apply code changes (with write permission)

$3

- Auto-save - Conversations are automatically saved
- Session picker - Choose which session to continue on startup
- Per-project sessions - Sessions stored in .codeep/sessions/
- Rename sessions - Give meaningful names with /rename
- Search history - Find past conversations with /search
- Export - Save to Markdown, JSON, or plain text

$3

- /diff - Review unstaged changes with AI assistance
- /diff --staged - Review staged changes
- /commit - Generate conventional commit messages

$3

- Automatic syntax highlighting for 12+ languages
- Copy code blocks to clipboard with /copy [n]
- Code blocks are numbered for easy reference

$3

- /paste command - Paste content from clipboard into chat
- Type /paste and press Enter to read clipboard content
- Shows preview with character/line count before sending
- Press Enter to send, Escape to cancel
- Works reliably in all terminals (no Ctrl+V issues)

$3

Codeep works as a full AI coding agent that autonomously:
- Creates, edits, and deletes files
- Executes shell commands (npm, git, build, test, etc.)
- Reads and analyzes your codebase
- Loops until the task is complete
- Reports all actions taken

Auto mode (default): Just describe what you want - no special commands needed:
``
> add error handling to src/api/index.ts
> run tests and fix any failures
> create a new React component for user settings
`

Manual mode: Use /agent when you want explicit control.

Agent Tools:
| Tool | Description |
|------|-------------|
| read_file | Read file contents |
| write_file | Create or overwrite files |
| edit_file | Edit specific text in files |
| delete_file | Delete files or directories |
| create_directory | Create folders |
| list_files | List directory contents |
| execute_command | Run shell commands |
| search_code | Search for patterns in code |
| fetch_url | Fetch content from URLs |

$3

- Undo actions - Revert any file change the agent made
- Session history - View and restore from previous agent sessions
- Action tracking - All file operations are logged for review

$3

- Save conversations - Continue where you left off
- Per-project context - Each project maintains its own history
- Automatic summarization - Old messages are summarized to save space

$3

- Agent can fetch documentation and web content
- Useful for looking up API docs, examples, etc.
- Automatic HTML-to-text conversion

$3

Agent automatically gathers relevant files before making changes:
- Analyzes imports and dependencies
- Reads related type definitions
- Understands project structure
- Prevents duplicate code and inconsistencies

$3

Built-in static analysis with /review:
- Security vulnerabilities (XSS, injection, hardcoded secrets)
- Performance issues (inefficient patterns)
- Type safety problems (any types, ts-ignore)
- Best practices and maintainability
- Generates a score (0-100)

$3

Agent asks clarifying questions when tasks are ambiguous:
`
You: "add authentication"
Agent: "What type of authentication do you want?
a) JWT tokens
b) Session-based
c) OAuth (Google/GitHub)"
`

$3

See exactly what will change before applying:
`diff
- const user = getUser();
+ const user = await getUser();
`

$3

Agent learns your coding preferences:
- Indentation style (tabs/spaces)
- Quote style (single/double)
- Naming conventions
- Preferred libraries
- Custom rules you define

$3

Predefined workflows for common development tasks. Execute with a single command:

`
/commit - Generate commit message and commit
/test - Generate tests for current code
/docs - Add documentation to code
/refactor - Improve code quality
/fix - Debug and fix issues
/component - Generate React/Vue component
/docker - Generate Dockerfile
`

50+ Built-in Skills:

| Category | Skills |
|----------|--------|
| Git | /commit (/c), /amend, /push (/p), /pull, /pr, /changelog, /branch, /stash, /unstash |
| Testing | /test (/t), /test-fix, /coverage, /e2e, /mock |
| Documentation | /docs (/d), /readme, /explain (/e), /api-docs, /translate |
| Refactoring | /refactor (/r), /types, /optimize (/o), /cleanup, /modernize, /migrate, /split, /rename |
| Debugging | /debug (/b), /fix (/f), /security, /profile, /log |
| Deployment | /build, /deploy, /release, /publish |
| Code Generation | /component, /api, /model, /hook, /service, /page, /form, /crud |
| DevOps | /docker, /ci, /env, /k8s, /terraform, /nginx, /monitor |

Shortcuts: Many skills have single-letter shortcuts (shown in parentheses).

Skill Parameters: Many skills accept parameters:
`
/component UserCard # Generate component named UserCard
/api users method=POST # Generate POST endpoint for users
/migrate "React 18" # Migrate to React 18
/model User fields=name,email # Generate User model with fields
`

Skill Chaining: Run multiple skills in sequence with +:
`
/commit+push # Commit then push
/test+commit+push # Test, commit if pass, then push
/build+deploy # Build then deploy
`

Search Skills:
`
/skills docker # Find skills related to docker
/skills testing # Find testing-related skills
`

Custom Skills: Create your own skills:
`
/skill create my-workflow # Creates template in ~/.codeep/skills/
/skill delete my-workflow # Delete custom skill
/skill help commit # Show skill details
`

Custom skill example (~/.codeep/skills/my-workflow.json):
`json
{
"name": "my-workflow",
"description": "My custom workflow",
"shortcut": "m",
"parameters": [
{ "name": "target", "description": "Target environment", "required": true }
],
"steps": [
{ "type": "command", "content": "npm run build" },
{ "type": "confirm", "content": "Deploy to ${target}?" },
{ "type": "agent", "content": "Deploy the application to ${target}" },
{ "type": "notify", "content": "Deployed to ${target}!" }
]
}
`

$3

Scan your project once and cache deep analysis for faster AI responses:

`
/scan # Full project scan - analyzes structure, dependencies, patterns
/scan status # Show last scan info (age, file count, project type)
/scan clear # Clear cached intelligence
`

What gets analyzed and cached:

| Category | Information |
|----------|-------------|
| Structure | File count, directory tree, language distribution |
| Dependencies | Runtime & dev dependencies, detected frameworks |
| Architecture | Patterns (MVC, Component-based), main modules, entry points |
| Scripts | Available npm/composer/make scripts |
| Conventions | Indentation style, quotes, semicolons, naming conventions |
| Testing | Test framework, test directory location |

Benefits:
- AI understands your project deeply without re-analyzing each time
- Faster responses - no need to scan files repeatedly
- Consistent context across sessions
- Framework-aware suggestions (React, Vue, Express, Django, etc.)

Storage: .codeep/intelligence.json (project-local)

Example output:
`


Project: my-app

Type: TypeScript/Node.js

Structure

- 156 files, 24 directories
- Languages: TypeScript React (89), TypeScript (45), JSON (12)
- Main directories: src, components, utils, hooks

Frameworks

React, Next.js

Architecture

Patterns: Component-based, File-based routing
Main modules: src, components, hooks, utils

Available Scripts

- dev: next dev
- build: next build
- test: vitest

Code Conventions

- Indentation: spaces
- Quotes: single
- Semicolons: no
- Naming: camelCase
`

$3

After making changes, the agent automatically:
1. Runs build to check for compilation errors
2. Runs tests to ensure nothing is broken
3. Runs type checking for TypeScript/PHP projects
4. If errors found → automatically tries to fix them (up to 3 attempts)
5. Reports final verification status

Supported project types:

| Language | Build | Test | Type Check |
|----------|-------|------|------------|
| Node.js/TypeScript | npm/yarn/pnpm/bun run build | npm test, vitest, jest | tsc --noEmit |
| Python | - | pytest | - |
| Go | go build | go test | - |
| Rust | cargo build | cargo test | - |
| PHP/Laravel | composer run build | phpunit, artisan test | php -l (syntax) |

$3

- API keys stored securely (macOS Keychain / Linux Secret Service)
- Per-project permissions (read-only or read-write)
- Input validation and sanitization
- Configurable rate limiting
- Agent sandboxed to project directory
- Dangerous commands blocked (rm -rf /, sudo, etc.)
- Confirmation mode for destructive actions

Installation

$3

`bash
curl -fsSL https://raw.githubusercontent.com/VladoIvankovic/Codeep/main/install.sh | bash
`

Custom installation directory:
`bash
curl -fsSL https://raw.githubusercontent.com/VladoIvankovic/Codeep/main/install.sh | INSTALL_DIR=~/.local/bin bash
`

Specific version:
`bash
curl -fsSL https://raw.githubusercontent.com/VladoIvankovic/Codeep/main/install.sh | VERSION=1.0.0 bash
`

$3

`bash
brew tap VladoIvankovic/codeep
brew install codeep
`

Update:
`bash
brew upgrade codeep
`

$3

`bash
npm install -g codeep
`

Update:
`bash
npm update -g codeep
`

$3

Download the latest binary for your platform from GitHub Releases:

| Platform | Binary |
|----------|--------|
| macOS Apple Silicon (M1/M2/M3/M4) | codeep-macos-arm64 |
| macOS Intel | codeep-macos-x64 |
| Linux x86_64 | codeep-linux-x64 |

`bash


Example for macOS Apple Silicon:


curl -fsSL https://github.com/VladoIvankovic/Codeep/releases/latest/download/codeep-macos-arm64 -o codeep
chmod +x codeep
sudo mv codeep /usr/local/bin/
`

Quick Start

`bash


Navigate to your project directory

cd /path/to/your/project

Start Codeep

codeep

On first run, enter your API key

Get one at: https://z.ai/subscribe?ic=NXYNXZOV14

`

After installation, codeep is available globally in your terminal. Simply run it from any project directory to start coding with AI assistance.

Commands

$3

| Command | Description |
|---------|-------------|
| /help | Show help and available commands |
| /status | Show current configuration status |
| /version | Show version and current provider/model |
| /update | Check for updates |
| /clear | Clear chat history and start new session |
| /exit | Quit application |

$3

| Command | Description |
|---------|-------------|
| /provider | Switch AI provider (Z.ai, MiniMax) |
| /model | Switch AI model |
| /protocol | Switch API protocol (OpenAI/Anthropic) |
| /lang | Set response language (12 languages supported) |
| /settings | Adjust temperature, max tokens, timeout, rate limits |

$3

| Command | Description |
|---------|-------------|
| /sessions | List and load saved sessions |
| /sessions delete | Delete a specific session |
| /rename | Rename current session |
| /search | Search through chat history |
| /export | Export chat to MD/JSON/TXT format |

$3

| Command | Description |
|---------|-------------|
| /apply | Apply file changes from AI response |
| /copy [n] | Copy code block to clipboard (n = block number, -1 = last) |

$3

| Command | Description |
|---------|-------------|
| /grant | Grant write permission for agent (opens permission dialog) |
| /agent | Run agent for a specific task (manual mode) |
| /agent-dry | Preview what agent would do without executing |
| /agent-stop | Stop a running agent |
| /undo | Undo the last agent action |
| /undo-all | Undo all actions from current session |
| /history | Show recent agent sessions |
| /changes | Show all file changes from current session |

$3

| Command | Description |
|---------|-------------|
| /diff | Review unstaged git changes |
| /diff --staged | Review staged git changes |
| /commit | Generate commit message for staged changes |
| /git-commit [msg] | Commit current changes with message |

$3

| Command | Description |
|---------|-------------|
| /context-save | Save current conversation for later |
| /context-load | Load previously saved conversation |
| /context-clear | Clear saved context for this project |

$3

| Command | Description |
|---------|-------------|
| /review | Run code review on changed files |
| /review | Review specific file |
| /learn | Learn preferences from project files |
| /learn status | Show learned preferences |
| /learn rule | Add a custom coding rule |

$3

| Command | Description |
|---------|-------------|
| /scan | Scan project and cache intelligence for AI |
| /scan status | Show last scan info |
| /scan clear | Clear cached intelligence |

$3

| Command | Description |
|---------|-------------|
| /skills | List all available skills |
| /skills | Search skills by keyword |
| /skills stats | Show skill usage statistics |
| /skill | Execute a skill (e.g., /skill commit) |
| /skill | Execute skill with parameters |
| /skill help | Show skill details and steps |
| /skill create | Create a new custom skill |
| /skill delete | Delete a custom skill |
| /c, /t, /d, etc. | Skill shortcuts |
| /commit+push | Skill chaining (run multiple skills) |

$3

| Command | Description |
|---------|-------------|
| /login | Login with API key |
| /logout | Logout (choose which provider) |

Keyboard Shortcuts

| Key | Action |
|-----|--------|
| Enter | Submit message |
| ↑ / ↓ | Navigate input history |
| Ctrl+L | Clear chat (same as /clear) |
| Escape | Cancel current request |

Supported Languages

Codeep can respond in 12 languages:

| Code | Language |
|------|----------|
| auto | Auto-detect (matches user's language) |
| en | English |
| zh | Chinese (中文) |
| es | Spanish (Español) |
| hi | Hindi (हिन्दी) |
| ar | Arabic (العربية) |
| pt | Portuguese (Português) |
| fr | French (Français) |
| de | German (Deutsch) |
| ja | Japanese (日本語) |
| ru | Russian (Русский) |
| hr | Croatian (Hrvatski) |

Syntax Highlighting

Code blocks are automatically highlighted for:

- Python
- JavaScript / TypeScript
- Java
- Go
- Rust
- Bash / Shell
- PHP
- HTML / CSS
- SQL

Project Permissions

When you run Codeep in a project directory for the first time:

1. Codeep asks for permission to access the project
2. You can grant:
- Read-only - AI can see and analyze your code
- Read + Write - AI can also suggest file modifications
3. Permissions are saved in .codeep/config.json

With write access enabled:
- AI can suggest file changes using special code blocks
- You'll be prompted to approve changes with Y/n
- Use /apply to manually apply changes from the last response

Configuration

$3

| Type | Location |
|------|----------|
| Global config | ~/.config/codeep/config.json |
| Project config | .codeep/config.json |
| Global sessions | ~/.codeep/sessions/ |
| Project sessions | .codeep/sessions/ |
| Global logs | ~/.codeep/logs/ |
| Project logs | .codeep/logs/ |

$3

| Variable | Description |
|----------|-------------|
| ZAI_API_KEY | Z.ai API key |
| ZHIPUAI_API_KEY | ZhipuAI API key (alternative) |
| MINIMAX_API_KEY | MiniMax API key |

$3

| Setting | Default | Description |
|---------|---------|-------------|
| Temperature | 0.7 | Response creativity (0.0 - 2.0) |
| Max Tokens | 8192 | Maximum response length |
| API Timeout | 60000ms | Request timeout |
| API Rate Limit | 30/min | Max API calls per minute |
| Command Rate Limit | 100/min | Max commands per minute |
| Agent Mode | ON | ON = agent runs automatically (requires write permission via /grant), Manual = use /agent |
| Agent API Timeout | 180000ms | Timeout per agent API call (auto-adjusted for complexity) |
| Agent Max Duration | 20 min | Maximum time for agent to run (5-60 min) |
| Agent Max Iterations | 100 | Maximum agent iterations (10-200) |
| Agent Confirmation | Dangerous | Never, Dangerous (default), or Always |
| Agent Auto-Commit | Off | Automatically commit after agent completes |
| Agent Branch | Off | Create new branch for agent commits |
| Agent Auto-Verify | On | Automatically run build/test after changes |
| Agent Max Fix Attempts | 3 | Max attempts to auto-fix errors |

Usage Examples

$3

First, grant write permission (required for Agent Mode ON to work):

`
> /grant


Opens permission dialog - select "Read + Write" for full agent access


`

With write access enabled, just describe what you want:

`
> add input validation to the login form


Agent reads the file, adds validation, writes changes

> the tests are failing, fix them


Agent runs tests, analyzes errors, fixes code, re-runs tests

> refactor src/utils to use async/await instead of callbacks


Agent reads files, refactors each one, verifies changes

> create a new API endpoint for user preferences


Agent creates route file, adds types, updates index


`

$3

`
> /diff --staged

AI reviews your staged changes and provides feedback

`

$3

`
> /agent add a dark mode toggle to settings

Explicitly runs agent for this task

> /agent-dry reorganize the folder structure

Shows what agent would do without making changes

`

$3

`
> Explain what a closure is in JavaScript
> Look at src/utils/api.ts and explain what it does
`

$3

`
> /rename feature-auth-implementation
Session renamed to: feature-auth-implementation

> /search authentication

Find all messages mentioning "authentication"

> /export

Export chat to markdown file

``

Architecture

Codeep is built with:

- React + Ink - Terminal UI framework
- TypeScript - Type-safe codebase
- Conf - Configuration management
- Node.js Keychain - Secure credential storage

License

Apache 2.0

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

Support

- Issues: GitHub Issues