mirror of
https://github.com/hanzoai/python-sdk.git
synced 2026-10-23 20:23:00 +00:00
docs(tools): add todo, computer, config tool documentation
- todo.md: Task management with list, add, update, remove, clear actions - computer.md: pyautogui Mac automation (mouse, keyboard, screenshots, windows) - config.md: Git-style configuration and 700+ programmer personas
This commit is contained in:
@@ -0,0 +1,271 @@
|
||||
# hanzo-tools-computer
|
||||
|
||||
Computer control via pyautogui for comprehensive Mac automation. Mouse, keyboard, screenshots, window management.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
pip install hanzo-tools-computer
|
||||
```
|
||||
|
||||
Or as part of the full toolkit:
|
||||
|
||||
```bash
|
||||
pip install hanzo-mcp[tools-all]
|
||||
```
|
||||
|
||||
## Overview
|
||||
|
||||
`hanzo-tools-computer` provides desktop automation:
|
||||
|
||||
- **Mouse** - click, drag, scroll, move
|
||||
- **Keyboard** - type, press, hotkey
|
||||
- **Screen** - screenshots, display info
|
||||
- **Windows** - focus, list, get active
|
||||
- **Image Location** - find UI elements
|
||||
- **Regions** - named areas for targeting
|
||||
|
||||
## Quick Start
|
||||
|
||||
```python
|
||||
# Click at coordinates
|
||||
computer(action="click", x=100, y=200)
|
||||
|
||||
# Type text
|
||||
computer(action="type", text="Hello, World!")
|
||||
|
||||
# Press keys
|
||||
computer(action="press", key="enter")
|
||||
computer(action="hotkey", keys=["command", "c"])
|
||||
|
||||
# Screenshot
|
||||
computer(action="screenshot")
|
||||
|
||||
# Get screen info
|
||||
computer(action="info")
|
||||
```
|
||||
|
||||
## Actions Reference
|
||||
|
||||
### Mouse Actions
|
||||
|
||||
```python
|
||||
# Click
|
||||
computer(action="click", x=100, y=200)
|
||||
computer(action="double_click", x=100, y=200)
|
||||
computer(action="right_click", x=100, y=200)
|
||||
computer(action="middle_click", x=100, y=200)
|
||||
|
||||
# Move
|
||||
computer(action="move", x=100, y=200, duration=0.5)
|
||||
computer(action="move_relative", dx=50, dy=-30)
|
||||
|
||||
# Drag
|
||||
computer(action="drag", x=300, y=400, duration=0.5)
|
||||
computer(action="drag_relative", dx=100, dy=0)
|
||||
|
||||
# Scroll
|
||||
computer(action="scroll", amount=5) # Scroll up
|
||||
computer(action="scroll", amount=-5) # Scroll down
|
||||
computer(action="scroll", amount=3, x=500, y=300) # At position
|
||||
```
|
||||
|
||||
### Keyboard Actions
|
||||
|
||||
```python
|
||||
# Type text (character by character)
|
||||
computer(action="type", text="Hello!", interval=0.05)
|
||||
|
||||
# Write text (instant, can clear first)
|
||||
computer(action="write", text="Instant text", clear=True)
|
||||
|
||||
# Press single key
|
||||
computer(action="press", key="enter")
|
||||
computer(action="press", key="tab")
|
||||
computer(action="press", key="escape")
|
||||
|
||||
# Key combinations
|
||||
computer(action="hotkey", keys=["command", "c"]) # Copy
|
||||
computer(action="hotkey", keys=["command", "v"]) # Paste
|
||||
computer(action="hotkey", keys=["command", "shift", "s"]) # Save as
|
||||
|
||||
# Hold/release keys
|
||||
computer(action="key_down", key="shift")
|
||||
computer(action="key_up", key="shift")
|
||||
```
|
||||
|
||||
### Screen Actions
|
||||
|
||||
```python
|
||||
# Full screenshot (returns base64)
|
||||
computer(action="screenshot")
|
||||
|
||||
# Region screenshot
|
||||
computer(action="screenshot_region", region=[100, 100, 500, 300])
|
||||
|
||||
# Get all displays
|
||||
computer(action="get_screens")
|
||||
|
||||
# Get screen size
|
||||
computer(action="screen_size")
|
||||
|
||||
# Current mouse position
|
||||
computer(action="position")
|
||||
|
||||
# Full info
|
||||
computer(action="info")
|
||||
```
|
||||
|
||||
### Image Location
|
||||
|
||||
Find UI elements by image matching:
|
||||
|
||||
```python
|
||||
# Find image on screen (returns center point)
|
||||
computer(action="locate", image_path="button.png")
|
||||
|
||||
# Find all matches
|
||||
computer(action="locate_all", image_path="icon.png")
|
||||
|
||||
# Get center point
|
||||
computer(action="locate_center", image_path="submit.png")
|
||||
|
||||
# Wait for image to appear
|
||||
computer(action="wait_for_image", image_path="loading.png", timeout=10)
|
||||
|
||||
# Wait while image is visible
|
||||
computer(action="wait_while_image", image_path="spinner.png", timeout=30)
|
||||
```
|
||||
|
||||
### Pixel Operations
|
||||
|
||||
```python
|
||||
# Get pixel color at point
|
||||
computer(action="pixel", x=100, y=200)
|
||||
|
||||
# Check if pixel matches color
|
||||
computer(action="pixel_matches", x=100, y=200, color=[255, 0, 0], tolerance=10)
|
||||
```
|
||||
|
||||
### Window Management
|
||||
|
||||
```python
|
||||
# Get active window info
|
||||
computer(action="get_active_window")
|
||||
|
||||
# List all windows
|
||||
computer(action="list_windows")
|
||||
|
||||
# Focus window by title
|
||||
computer(action="focus_window", title="Terminal")
|
||||
computer(action="focus_window", title=".*Code.*", use_regex=True)
|
||||
```
|
||||
|
||||
### Named Regions
|
||||
|
||||
Define reusable screen regions:
|
||||
|
||||
```python
|
||||
# Define a region
|
||||
computer(action="define_region", name="toolbar", x=0, y=0, width=1920, height=60)
|
||||
|
||||
# Screenshot region
|
||||
computer(action="region_screenshot", name="toolbar")
|
||||
|
||||
# Locate image within region
|
||||
computer(action="region_locate", name="toolbar", image_path="save_button.png")
|
||||
```
|
||||
|
||||
### Timing & Flow
|
||||
|
||||
```python
|
||||
# Sleep
|
||||
computer(action="sleep", value=2.0)
|
||||
|
||||
# Countdown with output
|
||||
computer(action="countdown", value=5)
|
||||
|
||||
# Set global pause between actions
|
||||
computer(action="set_pause", value=0.2)
|
||||
|
||||
# Enable/disable fail-safe (corner abort)
|
||||
computer(action="set_failsafe", value=True)
|
||||
```
|
||||
|
||||
### Batch Operations
|
||||
|
||||
Execute multiple actions in sequence:
|
||||
|
||||
```python
|
||||
computer(action="batch", actions=[
|
||||
{"action": "click", "x": 100, "y": 200},
|
||||
{"action": "type", "text": "Hello"},
|
||||
{"action": "press", "key": "enter"}
|
||||
])
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### UI Automation
|
||||
|
||||
```python
|
||||
# Click button and fill form
|
||||
computer(action="click", x=500, y=300) # Click form field
|
||||
computer(action="write", text="[email protected]", clear=True)
|
||||
computer(action="press", key="tab")
|
||||
computer(action="write", text="password123")
|
||||
computer(action="press", key="enter")
|
||||
```
|
||||
|
||||
### Screenshot Workflow
|
||||
|
||||
```python
|
||||
# Take screenshot, find element, click it
|
||||
computer(action="screenshot")
|
||||
result = computer(action="locate", image_path="login_button.png")
|
||||
if result["found"]:
|
||||
computer(action="click", x=result["x"], y=result["y"])
|
||||
```
|
||||
|
||||
### Window Management
|
||||
|
||||
```python
|
||||
# Focus app and interact
|
||||
computer(action="focus_window", title="Safari")
|
||||
computer(action="hotkey", keys=["command", "l"]) # Focus URL bar
|
||||
computer(action="write", text="https://example.com", clear=True)
|
||||
computer(action="press", key="enter")
|
||||
```
|
||||
|
||||
### Wait for UI State
|
||||
|
||||
```python
|
||||
# Wait for loading to finish
|
||||
computer(action="wait_while_image", image_path="spinner.png", timeout=30)
|
||||
|
||||
# Then continue
|
||||
computer(action="click", x=500, y=400)
|
||||
```
|
||||
|
||||
## Performance Features
|
||||
|
||||
- **Lazy loading** - pyautogui loads on first use (150ms+ startup savings)
|
||||
- **Cached screen info** - Display info cached for 5 seconds
|
||||
- **Thread pool executor** - All blocking operations run in threads
|
||||
- **Batch operations** - Multiple actions in single call
|
||||
|
||||
## Fail-Safe
|
||||
|
||||
By default, moving the mouse to any corner of the screen will raise an exception, allowing you to abort automation. Disable with:
|
||||
|
||||
```python
|
||||
computer(action="set_failsafe", value=False)
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use image location over coordinates** - More robust across resolutions
|
||||
2. **Add waits for UI transitions** - Use `wait_for_image` after actions
|
||||
3. **Define named regions** - Improves code readability
|
||||
4. **Enable fail-safe** - Keep the corner abort enabled during development
|
||||
5. **Use batch for sequences** - More efficient than individual calls
|
||||
@@ -0,0 +1,250 @@
|
||||
# hanzo-tools-config
|
||||
|
||||
Configuration and development mode management for Hanzo AI.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
pip install hanzo-tools-config
|
||||
```
|
||||
|
||||
Or as part of the full toolkit:
|
||||
|
||||
```bash
|
||||
pip install hanzo-mcp[tools-all]
|
||||
```
|
||||
|
||||
## Overview
|
||||
|
||||
`hanzo-tools-config` provides:
|
||||
|
||||
- **config** - Git-style configuration management
|
||||
- **mode** - Development mode/persona switching
|
||||
|
||||
## Config Tool
|
||||
|
||||
Manage settings with git-style configuration.
|
||||
|
||||
### Quick Start
|
||||
|
||||
```python
|
||||
# Get a value
|
||||
config(action="get", key="user.name")
|
||||
|
||||
# Set a value
|
||||
config(action="set", key="user.name", value="Alice")
|
||||
|
||||
# List all settings
|
||||
config(action="list")
|
||||
|
||||
# Delete a setting
|
||||
config(action="delete", key="user.name")
|
||||
```
|
||||
|
||||
### Actions
|
||||
|
||||
#### get
|
||||
|
||||
Get a configuration value.
|
||||
|
||||
```python
|
||||
config(action="get", key="editor.theme")
|
||||
config(action="get", key="tools.timeout")
|
||||
```
|
||||
|
||||
#### set
|
||||
|
||||
Set a configuration value.
|
||||
|
||||
```python
|
||||
config(action="set", key="editor.theme", value="dark")
|
||||
config(action="set", key="tools.timeout", value="30")
|
||||
```
|
||||
|
||||
#### list
|
||||
|
||||
List all configuration values.
|
||||
|
||||
```python
|
||||
config(action="list")
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"settings": {
|
||||
"user.name": "Alice",
|
||||
"editor.theme": "dark",
|
||||
"tools.timeout": "30"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### delete
|
||||
|
||||
Remove a configuration value.
|
||||
|
||||
```python
|
||||
config(action="delete", key="editor.theme")
|
||||
```
|
||||
|
||||
### Configuration Scopes
|
||||
|
||||
| Scope | Location | Priority |
|
||||
|-------|----------|----------|
|
||||
| Session | Memory | Highest |
|
||||
| Project | `.hanzo/config` | Medium |
|
||||
| Global | `~/.hanzo/config` | Lowest |
|
||||
|
||||
## Mode Tool
|
||||
|
||||
Switch between development modes/personas.
|
||||
|
||||
### Quick Start
|
||||
|
||||
```python
|
||||
# List available modes
|
||||
mode(action="list")
|
||||
|
||||
# Activate a mode
|
||||
mode(action="activate", name="guido")
|
||||
|
||||
# Show current mode
|
||||
mode(action="current")
|
||||
|
||||
# Show mode details
|
||||
mode(action="show", name="linus")
|
||||
```
|
||||
|
||||
### Actions
|
||||
|
||||
#### list
|
||||
|
||||
List all available development modes.
|
||||
|
||||
```python
|
||||
mode(action="list")
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"modes": [
|
||||
{"name": "guido", "description": "Guido van Rossum - Python creator"},
|
||||
{"name": "linus", "description": "Linus Torvalds - Linux/Git creator"},
|
||||
{"name": "rob", "description": "Rob Pike - Go language designer"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### activate
|
||||
|
||||
Activate a development mode.
|
||||
|
||||
```python
|
||||
mode(action="activate", name="guido")
|
||||
```
|
||||
|
||||
This changes:
|
||||
- Code style preferences
|
||||
- Review approach
|
||||
- Communication style
|
||||
- Tool recommendations
|
||||
|
||||
#### current
|
||||
|
||||
Show the currently active mode.
|
||||
|
||||
```python
|
||||
mode(action="current")
|
||||
```
|
||||
|
||||
#### show
|
||||
|
||||
Show details of a specific mode.
|
||||
|
||||
```python
|
||||
mode(action="show", name="linus")
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"name": "linus",
|
||||
"description": "Linus Torvalds - Linux/Git creator",
|
||||
"principles": [
|
||||
"Simple is better than complex",
|
||||
"Make it work, make it right, make it fast",
|
||||
"Read the code"
|
||||
],
|
||||
"preferences": {
|
||||
"language": "C",
|
||||
"style": "kernel",
|
||||
"testing": "rigorous"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Available Modes
|
||||
|
||||
The mode system includes 700+ programmer personas loaded from `hanzo-persona`:
|
||||
|
||||
| Category | Examples |
|
||||
|----------|----------|
|
||||
| Language Creators | guido (Python), linus (Linux/C), rob (Go), rich (Clojure) |
|
||||
| Industry Leaders | jeff (AWS), kelsey (Kubernetes), mitchellh (HashiCorp) |
|
||||
| Framework Authors | dan (React), evan (Vue), taylor (Laravel) |
|
||||
| Scientists | alan (Turing), grace (Hopper), ada (Lovelace) |
|
||||
|
||||
Each persona includes:
|
||||
- OCEAN personality traits
|
||||
- Behavioral patterns
|
||||
- Cognitive style
|
||||
- Communication preferences
|
||||
- Tool recommendations
|
||||
|
||||
## Examples
|
||||
|
||||
### Project Setup
|
||||
|
||||
```python
|
||||
# Set project-specific config
|
||||
config(action="set", key="project.language", value="python")
|
||||
config(action="set", key="project.style", value="black")
|
||||
config(action="set", key="tools.lsp", value="pyright")
|
||||
|
||||
# Activate appropriate mode
|
||||
mode(action="activate", name="guido")
|
||||
```
|
||||
|
||||
### Switching Contexts
|
||||
|
||||
```python
|
||||
# Working on Go project
|
||||
mode(action="activate", name="rob")
|
||||
config(action="set", key="project.language", value="go")
|
||||
|
||||
# Later, switching to Rust
|
||||
mode(action="activate", name="steve") # Steve Klabnik
|
||||
config(action="set", key="project.language", value="rust")
|
||||
```
|
||||
|
||||
### Checking Configuration
|
||||
|
||||
```python
|
||||
# See all settings
|
||||
config(action="list")
|
||||
|
||||
# Check specific setting
|
||||
timeout = config(action="get", key="tools.timeout")
|
||||
|
||||
# Check current mode
|
||||
current = mode(action="current")
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use hierarchical keys** - `category.setting` format
|
||||
2. **Set project config locally** - Use `.hanzo/config` for project-specific
|
||||
3. **Match mode to project** - Python project → guido mode
|
||||
4. **Review mode on start** - Check persona fits your current task
|
||||
@@ -0,0 +1,189 @@
|
||||
# hanzo-tools-todo
|
||||
|
||||
Task management tools for tracking progress and organizing work.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
pip install hanzo-tools-todo
|
||||
```
|
||||
|
||||
Or as part of the full toolkit:
|
||||
|
||||
```bash
|
||||
pip install hanzo-mcp[tools-all]
|
||||
```
|
||||
|
||||
## Overview
|
||||
|
||||
`hanzo-tools-todo` provides task management:
|
||||
|
||||
- **todo** - Unified task management with list, add, update, remove, clear operations
|
||||
|
||||
## Quick Start
|
||||
|
||||
```python
|
||||
# List all todos
|
||||
todo()
|
||||
todo(action="list")
|
||||
|
||||
# Add a new todo
|
||||
todo(action="add", content="Fix the authentication bug")
|
||||
|
||||
# Update status
|
||||
todo(action="update", id="abc123", status="in_progress")
|
||||
|
||||
# Mark complete
|
||||
todo(action="update", id="abc123", status="completed")
|
||||
|
||||
# Remove a todo
|
||||
todo(action="remove", id="abc123")
|
||||
|
||||
# Clear all todos
|
||||
todo(action="clear")
|
||||
```
|
||||
|
||||
## Actions Reference
|
||||
|
||||
### list
|
||||
|
||||
List all todos, optionally filtered by status.
|
||||
|
||||
```python
|
||||
# List all
|
||||
todo(action="list")
|
||||
|
||||
# Filter by status
|
||||
todo(action="list", filter="pending")
|
||||
todo(action="list", filter="in_progress")
|
||||
todo(action="list", filter="completed")
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"todos": [
|
||||
{"id": "abc123", "content": "Fix bug", "status": "in_progress", "priority": "high"},
|
||||
{"id": "def456", "content": "Write tests", "status": "pending", "priority": "medium"}
|
||||
],
|
||||
"count": 2
|
||||
}
|
||||
```
|
||||
|
||||
### add
|
||||
|
||||
Add a new todo item.
|
||||
|
||||
```python
|
||||
# Simple add
|
||||
todo(action="add", content="Implement feature X")
|
||||
|
||||
# With priority
|
||||
todo(action="add", content="Critical fix", priority="high")
|
||||
|
||||
# With status
|
||||
todo(action="add", content="Already started", status="in_progress")
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `content` (required): Todo description
|
||||
- `status`: Initial status - "pending" (default), "in_progress", "completed"
|
||||
- `priority`: Priority level - "low", "medium" (default), "high"
|
||||
|
||||
### update
|
||||
|
||||
Update an existing todo.
|
||||
|
||||
```python
|
||||
# Update status
|
||||
todo(action="update", id="abc123", status="completed")
|
||||
|
||||
# Update content
|
||||
todo(action="update", id="abc123", content="Updated description")
|
||||
|
||||
# Update priority
|
||||
todo(action="update", id="abc123", priority="high")
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `id` (required): Todo ID
|
||||
- `content`: New content
|
||||
- `status`: New status
|
||||
- `priority`: New priority
|
||||
|
||||
### remove
|
||||
|
||||
Remove a todo by ID.
|
||||
|
||||
```python
|
||||
todo(action="remove", id="abc123")
|
||||
```
|
||||
|
||||
### clear
|
||||
|
||||
Clear all todos.
|
||||
|
||||
```python
|
||||
todo(action="clear")
|
||||
```
|
||||
|
||||
## Status Workflow
|
||||
|
||||
```
|
||||
pending → in_progress → completed
|
||||
↑_________| (can go back if needed)
|
||||
```
|
||||
|
||||
**Statuses:**
|
||||
- `pending` - Not yet started
|
||||
- `in_progress` - Currently being worked on
|
||||
- `completed` - Finished
|
||||
|
||||
## Priority Levels
|
||||
|
||||
- `high` - Urgent, do first
|
||||
- `medium` - Normal priority (default)
|
||||
- `low` - Can wait
|
||||
|
||||
## Storage
|
||||
|
||||
Todos are stored per-session in memory. For persistent todos, use the memory tools to save to disk.
|
||||
|
||||
## Examples
|
||||
|
||||
### Project Workflow
|
||||
|
||||
```python
|
||||
# Add tasks for a feature
|
||||
todo(action="add", content="Design API schema", priority="high")
|
||||
todo(action="add", content="Implement endpoints", priority="high")
|
||||
todo(action="add", content="Write tests", priority="medium")
|
||||
todo(action="add", content="Update documentation", priority="low")
|
||||
|
||||
# Start working
|
||||
todo(action="update", id="<design_id>", status="in_progress")
|
||||
|
||||
# Complete and move on
|
||||
todo(action="update", id="<design_id>", status="completed")
|
||||
todo(action="update", id="<implement_id>", status="in_progress")
|
||||
```
|
||||
|
||||
### Tracking Progress
|
||||
|
||||
```python
|
||||
# Check what's in progress
|
||||
todo(action="list", filter="in_progress")
|
||||
|
||||
# Check what's pending
|
||||
todo(action="list", filter="pending")
|
||||
|
||||
# Check completed
|
||||
todo(action="list", filter="completed")
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use meaningful descriptions** - Clear content helps tracking
|
||||
2. **Set appropriate priorities** - High for blockers, medium for features
|
||||
3. **Update status promptly** - Keep todos current
|
||||
4. **Clear completed items** - Periodically clean up finished tasks
|
||||
Reference in New Issue
Block a user