AI-powered coding assistant built for the terminal. Multiple LLM providers, project-aware context, and a seamless development workflow.
npm install codeep
Deep into Code.
AI-powered coding assistant built for the terminal. Multiple LLM providers, project-aware context, and a seamless development workflow.
/provider.codeep/sessions//rename/search/diff - Review unstaged changes with AI assistance/diff --staged - Review staged changes/commit - Generate conventional commit messages/copy [n]/paste command - Paste content from clipboard into chat/paste and press Enter to read clipboard contentCodeep 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 |
:
- 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.jsStructure
- 156 files, 24 directories
- Languages: TypeScript React (89), TypeScript (45), JSON (12)
- Main directories: src, components, utils, hooksFrameworks
React, Next.jsArchitecture
Patterns: Component-based, File-based routing
Main modules: src, components, hooks, utilsAvailable Scripts
- dev: next dev
- build: next build
- test: vitestCode 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 statusSupported 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 actionsInstallation
$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/projectStart Codeep
codeepOn 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.jsonWith 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 responseConfiguration
$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
``Codeep is built with:
- React + Ink - Terminal UI framework
- TypeScript - Type-safe codebase
- Conf - Configuration management
- Node.js Keychain - Secure credential storage
Apache 2.0
Contributions are welcome! Please open an issue or submit a pull request on GitHub.
- Issues: GitHub Issues