Zeno skill wrapper for Clawdbot

README.md

Zeno Skill for Clawdbot

A wrapper skill that integrates Zeno recursive codebase analysis with Clawdbot.

Quick Start

1. Copy this folder to ~/.clawdbot/skills/zeno/
2. Clone the main Zeno repo for runtime configs:

   git clone https://github.com/anth0nylawrence/zeno.git /tmp/zeno-upstream
   cp -r /tmp/zeno-upstream/claude-code ~/.clawdbot/skills/zeno/
   cp -r /tmp/zeno-upstream/codex ~/.clawdbot/skills/zeno/

3. Use natural language: "Analyze the auth flow in ~/Projects/myapp using Zeno"

Contents

• SKILL.md - Main skill documentation (loaded by Clawdbot)
• scripts/zeno-analyze.sh - Wrapper script for quick analysis
• README.md - This file

Usage

Ask your Clawdbot:

• "Use Zeno to find security issues in this repo"
• "Trace all database queries with Zeno"
• "Map the architecture of src/api/"

Author

Skill wrapper by Clawd 🦞 Zeno by Anthony Lawrence (@anth0nylawrence)

SKILL.md

Zeno - Unbounded Codebase Analysis

Recursive decomposition for massive codebase analysis without context rot. Evidence-first, read-only workflow.

Overview

Zeno keeps the codebase external (not in your prompt) and uses surgical retrieval (grep, peek, read_file) to pull only what's needed. Every claim is backed by file:line citations.

Installation

# Clone into your skills folder
git clone https://github.com/anth0nylawrence/zeno.git ~/.clawdbot/skills/zeno

# Or install via ClawdHub (when available)
clawdhub install anth0nylawrence/zeno

Setup

Zeno integrates with Claude Code or Codex. Copy the appropriate config:

For Claude Code:

cp ~/.clawdbot/skills/zeno/claude-code/* /path/to/your/repo/

For Codex:

cp ~/.clawdbot/skills/zeno/codex/* /path/to/your/repo/

Usage

Natural Language Triggers

Zeno activates when you ask analysis questions:

Intent	Example Prompt
Trace callers	"Who calls handleAuth()?"
Security audit	"Find SQL injection risks"
Architecture	"Map the dependency graph for payments/"
Dead code	"Find unused exports in src/utils"
Data flow	"Trace user input from API to database"

Via Wrapper Script

# Start Zeno analysis on a repo
~/.clawdbot/skills/zeno/scripts/zeno-analyze.sh /path/to/repo "your question"

How It Works

1. Corpus stays external - not stuffed into prompt
2. Recursive decomposition - complex queries split into sub-queries
3. Surgical retrieval - grep, peek, read_file pull 50-100 lines at a time
4. Evidence discipline - every claim has file:line citation
5. Budget controls - prevents runaway token usage

Commands

Command	Description
grep <pattern>	Search codebase for pattern
peek <file> [start] [end]	View lines from file
read_file <file>	Read entire file
ls <path>	List directory contents
find <pattern>	Find files by name

Output Blocks

Zeno produces structured output:

<zeno:claim>
Authentication bypassed when JWT secret is empty
<evidence file="src/auth.ts" lines="42-48">
if (!process.env.JWT_SECRET) {
  return true; // BUG: allows all requests
}
</evidence>
</zeno:claim>

Integration with Clawdbot

Spawn as Coding Agent

# In your chat, ask Clawdbot to analyze with Zeno
"Use Zeno to audit the security of ~/Projects/myapp"

Clawdbot will spawn a coding agent with Zeno configured.

Direct Analysis

For quick analysis, use the wrapper script directly via bash tool.

Configuration

Create .zeno/config.json in target repo:

{
  "budgets": {
    "max_tokens_per_query": 50000,
    "max_files_per_session": 100
  },
  "exclude": [
    "node_modules",
    ".git",
    "dist"
  ]
}

Troubleshooting

"Context overflow" - Zeno should prevent this, but if it happens, the corpus is too large for a single query. Break into smaller questions.

"No evidence found" - Query might be too vague. Be specific about files/functions.

Slow analysis - Large repos take time. Use exclude to skip irrelevant dirs.

Resources

• GitHub: https://github.com/anth0nylawrence/zeno
• Research: RLM paper (arxiv.org/abs/2512.24601)
• Author: @buddadoc

Credits

Created by Anthony Lawrence (@anth0nylawrence / @buddadoc)

zeno-analyze.sh

#!/bin/bash
# zeno-analyze.sh - Wrapper script to run Zeno analysis on a codebase
# Usage: zeno-analyze.sh <repo_path> "<question>"

set -e

REPO_PATH="${1:-.}"
QUESTION="${2:-"Analyze this codebase architecture"}"

# Validate repo path
if [ ! -d "$REPO_PATH" ]; then
    echo "Error: Repository path '$REPO_PATH' does not exist"
    exit 1
fi

# Get absolute path
REPO_PATH=$(cd "$REPO_PATH" && pwd)

echo "=== Zeno Analysis ==="
echo "Repository: $REPO_PATH"
echo "Question: $QUESTION"
echo "===================="
echo ""

# Check if Zeno config exists in repo
if [ ! -d "$REPO_PATH/.zeno" ]; then
    echo "Note: No .zeno/ config found. Using defaults."
    echo ""
fi

# Check for Claude Code or Codex setup
if [ -f "$REPO_PATH/CLAUDE.md" ] || [ -f "$REPO_PATH/.claude/settings.json" ]; then
    echo "Detected: Claude Code configuration"
    RUNTIME="claude"
elif [ -f "$REPO_PATH/codex.md" ] || [ -f "$REPO_PATH/.codex" ]; then
    echo "Detected: Codex configuration"
    RUNTIME="codex"
else
    echo "Warning: No Claude Code or Codex config detected."
    echo "Zeno works best when integrated with a coding agent."
    echo ""
    echo "To set up:"
    echo "  Claude Code: cp ~/.clawdbot/skills/zeno/claude-code/* $REPO_PATH/"
    echo "  Codex:       cp ~/.clawdbot/skills/zeno/codex/* $REPO_PATH/"
    echo ""
    RUNTIME="none"
fi

# Generate analysis prompt
PROMPT="Using Zeno methodology (evidence-first, recursive decomposition):

$QUESTION

Requirements:
1. Keep the codebase external - don't paste entire files
2. Use surgical retrieval (grep, peek specific lines)
3. Every claim must have file:line citation
4. Decompose complex queries into sub-queries
5. Stay read-only - analysis only, no modifications

Start by exploring the repo structure, then drill down based on findings."

echo ""
echo "=== Analysis Prompt ==="
echo "$PROMPT"
echo "======================="
echo ""

# If runtime detected, suggest how to run
case $RUNTIME in
    claude)
        echo "To run analysis with Claude Code:"
        echo "  cd $REPO_PATH && claude \"$QUESTION\""
        ;;
    codex)
        echo "To run analysis with Codex:"
        echo "  cd $REPO_PATH && codex \"$QUESTION\""
        ;;
    *)
        echo "To run analysis, set up a coding agent first,"
        echo "or use this prompt with your preferred AI tool."
        ;;
esac

echo ""
echo "=== Quick Repo Stats ==="
echo "Files: $(find "$REPO_PATH" -type f -not -path '*/\.*' -not -path '*/node_modules/*' | wc -l | tr -d ' ')"
echo "Lines: $(find "$REPO_PATH" -type f -name '*.ts' -o -name '*.js' -o -name '*.py' -o -name '*.go' -o -name '*.rs' 2>/dev/null | head -100 | xargs wc -l 2>/dev/null | tail -1 | awk '{print $1}' || echo 'N/A')"
echo "========================"

@steipete is this working well for you?