Claude Tools

A practical, developer-friendly CLI for running Claude workflows from your terminal.

Turn repeatable prompting into reusable commands for code review, diff analysis, file summaries, error explanation, and batch jobs.

---

Overview

Claude Tools is a clean Python CLI that helps you use Claude for common engineering and writing workflows without rewriting prompts every time.

It gives you:

• a simple terminal interface
• reusable prompt templates
• environment-based configuration
• file and stdin support
• JSON / JSONL batch execution
• a clean base for adding more Claude-powered commands later

This project is intentionally lightweight: no web app, no database, no heavy framework. Just a solid CLI that is easy to install, extend, and ship.

---

Features

Terminal-first workflow	Run Claude directly from your shell using a small, focused CLI.
Reusable templates	Built-in prompt templates for code review, PR summaries, diff review, test generation, commit messages, meeting notes, file summaries, and error analysis.
File + stdin support	Pass prompts directly, read piped input, or analyze local text files.
Batch processing	Run multiple jobs from .json or .jsonl files.
Configurable defaults	Use .env and environment variables for API key, model, token limits, and system prompt.
Developer-friendly output	Rich terminal output, optional JSON responses, and file export support.
Production-ready project scaffold	Includes packaging, tests, and GitHub Actions CI.

---

Built-in Commands

Command	Purpose
claude-tools version	Show installed version
claude-tools config	Show resolved configuration with redacted API key
claude-tools templates	List available templates
claude-tools templates -v	Show templates with descriptions and variables
claude-tools template-info <name>	Show one template in detail
claude-tools render <template>	Render a template locally without calling the API
claude-tools ask ...	Send a direct prompt or template-based prompt to Claude
claude-tools summarize-file <path>	Summarize a local text file
claude-tools explain-error <path>	Explain an error log or stack trace
claude-tools review-diff <path>	Review a Git diff
claude-tools batch <jobs.json>	Run multiple prompts from JSON or JSONL
claude-tools save-example-batch <path>	Generate a sample batch file

---

Built-in Templates

Template	What it does
code_review	Reviews code for bugs, clarity, maintainability, and test gaps
pr_summary	Summarizes a pull request or change set
meeting_notes	Converts rough notes into structured meeting notes
file_summary	Summarizes a file with key risks and next steps
error_explain	Explains stack traces or logs and suggests fixes
diff_review	Reviews a Git diff like a senior engineer
test_generation	Generates high-value test ideas
commit_message	Produces a concise conventional commit message

---

Installation

1) Clone the repository

git clone https://github.com/HimaniSingh3/claude-tools.git
cd claude-tools

2) Create and activate a virtual environment

python -m venv .venv
source .venv/bin/activate

On Windows PowerShell:

python -m venv .venv
.venv\Scripts\Activate.ps1

3) Install the package

pip install -e .

For development tools as well:

pip install -e .[dev]

---

Configuration

Create a local environment file from the example:

cp .env.example .env

Set your Anthropic API key:

ANTHROPIC_API_KEY=your_api_key_here
CLAUDE_MODEL=claude-sonnet-4-6
CLAUDE_MAX_TOKENS=1200
CLAUDE_SYSTEM_PROMPT=You are a concise and practical assistant.

Supported environment variables

Variable	Required	Default	Description
ANTHROPIC_API_KEY	Yes for API calls	—	Your Anthropic API key
CLAUDE_MODEL	No	claude-sonnet-4-6	Default Claude model
CLAUDE_MAX_TOKENS	No	1200	Default max output tokens
CLAUDE_SYSTEM_PROMPT	No	You are a concise and practical assistant.	Default system prompt

Check the resolved configuration anytime:

claude-tools config

---

Quick Start

Ask Claude directly

claude-tools ask "Explain Python context managers with a simple example"

Render a template without calling the API

claude-tools render code_review --var code="def add(a,b): return a+b"

Use a template and send it to Claude

claude-tools ask --template code_review --var code="def add(a,b): return a+b"

Read prompt content from stdin

echo "Summarize the pros and cons of using SQLite in desktop apps" | claude-tools ask --stdin

Save the response to a file

claude-tools ask "Draft a release note for version 1.0.0" --save RELEASE_NOTES.md

Output machine-readable JSON

claude-tools ask "List 3 API design mistakes" --json

---

Workflow Examples

Summarize a local file

claude-tools summarize-file README.md

Add extra instructions:

claude-tools summarize-file README.md --instructions "Focus on developer onboarding gaps"

Explain a stack trace or log file

claude-tools explain-error logs.txt

Or pipe logs from another command:

python app.py 2>&1 | claude-tools explain-error --stdin

Review a diff file

git diff > changes.diff
claude-tools review-diff changes.diff

Or pipe the diff directly:

git diff | claude-tools review-diff --stdin

Inspect available templates

claude-tools templates -v
claude-tools template-info diff_review

---

Batch Jobs

Claude Tools can run multiple jobs from either a JSON array or a JSONL file.

Generate an example batch file

claude-tools save-example-batch examples/jobs.json

Run a batch

claude-tools batch examples/jobs.json

Save batch results

claude-tools batch examples/jobs.json --output results.json

Dry run a batch without calling the API

claude-tools batch examples/jobs.json --dry-run

Example batch format

[
  {
    "name": "readme-summary",
    "prompt": "Summarize this project in 5 bullets."
  },
  {
    "name": "review-snippet",
    "template": "code_review",
    "variables": {
      "code": "def add(a, b): return a + b"
    }
  }
]

Each job supports:

• name — optional human-readable identifier
• prompt — direct prompt text
• template — template name instead of raw prompt
• variables — template variables object
• system — optional system prompt override
• metadata — extra metadata preserved in results

A job must define either prompt or template.

---

Command Reference

ask

claude-tools ask [PROMPT] [OPTIONS]

Common options:

• --template — render a named template first
• --var key=value — pass template variables
• --stdin — read the prompt body from stdin
• --system — override the default system prompt
• --model — override the configured model
• --max-tokens — override the configured max token count
• --temperature — set request temperature
• --dry-run — render only, do not call the API
• --json — print structured response metadata
• --save PATH — write response text to a file

summarize-file

Summarizes a local text file using the built-in file_summary template.

claude-tools summarize-file path/to/file.txt

explain-error

Explains a text log, stack trace, or piped stderr output.

claude-tools explain-error error.log

review-diff

Reviews a Git diff from a file or stdin.

claude-tools review-diff changes.diff

render

Renders a template locally for inspection or debugging.

claude-tools render commit_message --var changes="fix auth timeout"

---

Project Structure

claude-tools/
├── .github/workflows/ci.yml
├── .env.example
├── .gitignore
├── LICENSE
├── README.md
├── examples/
│   └── jobs.json
├── claude_tools/
│   ├── __init__.py
│   ├── batch.py
│   ├── cli.py
│   ├── client.py
│   ├── config.py
│   ├── io_utils.py
│   └── templates.py
├── tests/
│   ├── test_batch.py
│   ├── test_cli_helpers.py
│   └── test_templates.py
└── pyproject.toml

---

Development

Run tests

pytest

Run Ruff

ruff check .

Build the package

python -m build

---

Troubleshooting

“ANTHROPIC_API_KEY is missing”

Set your API key in .env or in your shell environment.

“The 'anthropic' package is not installed”

Install the package in editable mode:

pip install -e .

Template variable errors

If you see an error like:

Missing required template variable: code

make sure every required template field is passed with --var key=value.

Non-text files

summarize-file, explain-error, and review-diff are designed for text input. Binary files are not supported.

---

Why this project exists

A lot of Claude usage starts as ad hoc prompting and stays that way for too long.

This project turns that into a repeatable tool:

• prompts become reusable templates
• terminal workflows become one-liners
• repeated tasks become scripts instead of copy-paste rituals

It is a strong base for future commands like:

• review-pr
• summarize-commit
• generate-tests-from-file
• Git-aware repository helpers
• custom user-defined templates

---

License

This project is licensed under the MIT License. See the LICENSE file for details.