Codeep

Features

Multi-Provider Support

• 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

Project Context Awareness

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)

Session Management

• 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

Git Integration

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

Code Block Management

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

Clipboard Paste

• /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)

Autonomous Agent Mode

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 <task> 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 |

Undo & History

• 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

Context Persistence

• 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

Web Fetch

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

Smart Context

Agent automatically gathers relevant files before making changes:

• Analyzes imports and dependencies
• Reads related type definitions
• Understands project structure
• Prevents duplicate code and inconsistencies

Code Review Mode

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)

Interactive Mode

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)"

Diff Preview

See exactly what will change before applying:

- const user = getUser();
+ const user = await getUser();

Learning Mode

Agent learns your coding preferences:

• Indentation style (tabs/spaces)
• Quote style (single/double)
• Naming conventions
• Preferred libraries
• Custom rules you define

Skills System

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):

{
  "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}!" }
  ]
}

Project Intelligence (/scan)

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

Self-Verification

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) |

Security Features

• 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

Option 1: curl (Quickest)

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

Custom installation directory:

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

Specific version:

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

Option 2: Homebrew (macOS/Linux)

brew tap VladoIvankovic/codeep
brew install codeep

Update:

brew upgrade codeep

Option 3: npm

npm install -g codeep

Update:

npm update -g codeep

Option 4: Manual Binary

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 |

# 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

# 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

General

| 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 |

AI Configuration

| 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 |

Session Management

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

Code & Files

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

Agent Mode

| Command | Description | |---------|-------------| | /grant | Grant write permission for agent (opens permission dialog) | | /agent <task> | Run agent for a specific task (manual mode) | | /agent-dry <task> | 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 |

Git Integration

| 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 |

Context Persistence

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

Code Review & Learning

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

Project Intelligence

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

Skills

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

Authentication

| 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

Config Locations

| 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/ |

Environment Variables

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

Settings (/settings)

| 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

Autonomous Coding (Agent Mode ON)

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

Code Review

> /diff --staged
# AI reviews your staged changes and provides feedback

Manual Agent Mode

> /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

Basic Chat (when agent mode is manual or read-only)

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

Session Management

> /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