JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 9
  • Score
    100M100P100Q66469F
  • License MIT

AI agents that actually do things - real actions, real changes, real time

Package Exports

  • @ziggler/clanker
  • @ziggler/clanker/package.json

Readme

Clanker

npm version license node version downloads

AI agents that actually do things

Not just suggestions—real actions, real changes, real time.

Want to use it in cursor? No problem!

https://github.com/user-attachments/assets/6f0bce3f-13dd-483d-ba99-4017f953f9a4

Standard tty/(kitty) terminal

https://github.com/user-attachments/assets/2465c9b7-8f13-4a39-9486-f7ca032dadc4

Quick Start

# Install Clanker globally
npm install -g @ziggler/clanker

# Install essential tools
clanker -I ziggle-dev/bash
clanker -I ziggle-dev/view-file
clanker -I ziggle-dev/write-to-file
clanker -I ziggle-dev/multi-edit
clanker -I ziggle-dev/search

# Start using Clanker
clanker

Clanker will guide you through API key setup on first run.

What's New

v0.3.1

  • 🔄 Update All Tools: Update all installed tools at once with clanker --update
  • 🚀 Self-Update: Keep clanker up-to-date with clanker -U or clanker upgrade

v0.3.0

  • 🪝 Hook System: Comprehensive event-driven architecture for extending Clanker
  • 💾 Session Management: Persistent chat sessions with auto-save and history
  • 📦 Local Tool Installation: Install tools directly from local directories with --local
  • 🔧 Enhanced Tool Context: Tools can now execute other tools and access the hook system
  • 🔗 Tool Dependencies: Tools can declare dependencies that are automatically installed

What Can It Do?

# Refactor code intelligently
> "Replace all console.log with our logger utility"
✓ Found 47 instances across 12 files
✓ Applied context-aware replacements
✓ All tests still passing

# Understand and modify complex codebases  
> "Add error handling to all async functions"
✓ Analyzed 23 async functions
✓ Added try-catch with appropriate error handling
✓ Preserved existing logic flow

# Execute multi-step workflows
> "Set up a new React component with tests"
✓ Created Button.tsx with TypeScript props
✓ Added Button.test.tsx with coverage
✓ Updated component index exports

# Work with files and directories
> "Show me the structure of the src folder"
✓ Listed all files and directories
✓ Highlighted important configuration files

# Search and analyze code
> "Find all TODO comments in the codebase"
✓ Searched across 156 files
✓ Found 23 TODO comments
✓ Grouped by priority and file location

Key Features

🧠 Intelligent File Editing

Advanced order-invariant diff algorithm for reliable file editing. Multiple edit strategies ensure changes are applied correctly even in complex scenarios.

🛠️ Extensible Tool System

Clanker uses a modular tool system where every action is performed by a tool. Tools are distributed through the package registry and can be easily installed.

🎨 Beautiful Terminal UI

React-powered terminal interface with:

  • Syntax highlighting for code
  • Real-time streaming responses
  • Progress indicators for long operations
  • Keyboard shortcuts for efficiency

🔐 Safety First

  • Confirmation prompts for file modifications
  • Dry-run mode for testing changes
  • Full operation history
  • Built-in safeguards against destructive operations

Tool Ecosystem

Package Manager Commands

# List all available tools in the registry
clanker -A              # or clanker --list-available
clanker -A 2           # Show page 2 of available tools

# Search for specific tools
clanker -S bash         # or clanker --search bash
clanker -S "todo"      # Search for todo-related tools

# Install tools from the registry
clanker -I ziggle-dev/bash              # or clanker --install ziggle-dev/bash
clanker -I ziggle-dev/bash@1.0.0        # Install specific version

# List installed tools
clanker -L              # or clanker --list

# Uninstall tools
clanker --uninstall ziggle-dev/bash

# Update tools to latest version
clanker --update ziggle-dev/bash        # Update specific tool
clanker --update                        # Update all installed tools

# Upgrade clanker itself
clanker -U                              # or clanker --upgrade
clanker upgrade                         # or clanker self-update

# Clear package cache
clanker --clear-cache

Available Tools

Clanker uses an opt-in tool system. Install only the tools you need:

Essential Tools:

  • ziggle-dev/bash - Execute shell commands safely
  • ziggle-dev/view-file - Read and analyze files
  • ziggle-dev/write-to-file - Create or overwrite files
  • ziggle-dev/multi-edit - Advanced file editing with conflict resolution
  • ziggle-dev/search - Fast code search with ripgrep

File Management:

  • ziggle-dev/list - Browse directory contents
  • ziggle-dev/pwd - Show current directory
  • ziggle-dev/remove - Delete files and directories

Task Management:

  • ziggle-dev/create-todo-list - Create task lists
  • ziggle-dev/update-todo-list - Update task status

Utilities:

  • ziggle-dev/input - Get user input during operations
  • ziggle-dev/summarize - Summarize long content (coming soon)

View all available tools with clanker -A or clanker --list-available

Creating Your Own Tools

Create and share your own tools with the community:

# Use the tool creation wizard
npx create-clanker-tool my-awesome-tool

# Or start from template
git clone https://github.com/zigglers/rachet-tool my-tool
cd my-tool

# Install dependencies
npm install

# Test locally
npm run build
clanker -I ./  # Install from current directory

# Publish to registry
npm run publish

Visit the Tool Development Guide for detailed instructions.

Hook System

Clanker v0.3.0 introduces a powerful hook system that allows tools and users to extend functionality through event-driven programming.

Hook Events

  • PreToolUse: Fired before any tool execution (can block or modify)
  • PostToolUse: Fired after tool execution (can process results)
  • PreMessage: Fired before messages are added to the conversation
  • PostMessage: Fired after messages are processed
  • SessionStart: Fired when a session begins
  • UserPromptSubmit: Fired when user submits a prompt

Configuring Hooks

Add hooks to your settings files:

// ~/.clanker/settings.json or project .clanker/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "bash",
        "hooks": [{
          "type": "command",
          "command": "echo 'Running bash command: $TOOL_INPUT' >> audit.log"
        }]
      }
    ]
  }
}

Dynamic Hook Registration

Tools can register hooks programmatically:

export default async function(args: ToolArguments, context: ToolContext) {
  // Register a hook
  context.hooks.register({
    id: 'my-hook',
    name: 'My Custom Hook',
    event: HookEvent.PostMessage,
    handler: async (input, context) => {
      // Hook logic here
      return { continue: true };
    }
  });
}

Local Tool Development

Develop and test tools locally before publishing:

# Install a tool from local directory
clanker install --local ./my-tool

# The tool is installed with its version from package.json
clanker list  # Shows: my-org/my-tool@1.0.0

Session Management

Clanker now automatically saves your conversations and maintains session history:

  • Sessions are saved to ~/.clanker/sessions/
  • Auto-save every 30 seconds (configurable)
  • Resume previous sessions with context
  • Export transcripts as JSONL

Session Commands

# Sessions are managed automatically
clanker  # Starts new or resumes last session

# View session info (when in chat)
> /session

# Export current session
> /export

Common Tasks

Getting Started

# Start a conversation with Clanker
clanker

# Ask Clanker to help with a specific task
> "Help me refactor this function to use async/await"
> "Find all TODO comments in the project"
> "Create a new React component with TypeScript"

Working with Files

# View file contents
> "Show me the package.json file"

# Edit files
> "Add error handling to the login function"

# Create new files
> "Create a new test file for UserService"

# Search code
> "Find all instances of console.log"

Running Commands

# Execute shell commands (requires bash tool)
> "Run npm test"
> "Show me the git status"
> "Install the lodash package"

Configuration

Clanker stores configuration in ~/.clanker/:

~/.clanker/
├── settings.json      # API keys and preferences
├── tools/             # Installed tools
└── history/           # Command history

Supported AI Providers

  • xAI Grok (default) - Fast and capable
  • OpenAI - GPT-4 and other models
  • Anthropic - Claude models
  • Custom - Any OpenAI-compatible endpoint

Setting Up Your API Key

On first run, Clanker will prompt you for an API key. You can also configure it manually:

# During first run
clanker
# Follow the prompts to enter your API key

# Or set environment variable
export CLANKER_API_KEY="your-api-key-here"

# Or add to ~/.clanker/settings.json
{
  "apiKey": "your-api-key-here",
  "provider": "grok"
}

Advanced Workflows

Refactoring a Codebase

> "Update all imports from 'lib/' to '@/lib/'"
> "Convert all class components to functional components"
> "Add TypeScript types to all exported functions"

Setting Up a New Project

> "Create a new Express API with TypeScript"
> "Set up ESLint and Prettier with sensible defaults"
> "Create a GitHub Actions workflow for CI/CD"

Debugging Issues

> "Find all console.error calls and add stack traces"
> "Add debug logging to the authentication flow"
> "Check for potential race conditions in async code"

Managing Tasks

# Create a todo list (requires todo tools)
> "Create a todo list for implementing user authentication"
> "Update task 3 to completed"
> "Show me all pending tasks"

Philosophy

Traditional AI assistants are suggestion engines. Clanker is different—it's an action engine.

Instead of:

"Here's how you could refactor this code..."

Clanker says:

"I'll refactor this code. Here's what I'm changing... Approve? [Y/n]"

This shift from passive suggestions to active assistance means you spend less time copying code and more time reviewing and shipping changes.

Documentation

Contributing

We welcome contributions! Here's how to get involved:

Development Setup

# Clone the repo
git clone https://github.com/zigglers/clanker.git
cd clanker

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Build for production
npm run build

Community

License

MIT © Ziggler

Stop copying suggestions. Start shipping changes.

⭐ Star on GitHub • 📚 Get Started • 🐦 Share