yoker 0.4.0

A Python agent harness with configurable tools and guardrails - one who yokes agents together

Yoker

A Python agent harness with configurable tools, guardrails, and Ollama backend integration.

Installation

pip install yoker

Quick Start

python -m yoker

Or with an agent definition:

python -m yoker --agent examples/agents/researcher.md

Example session:

Why Yoker?

Yoker fills a unique gap in the coding agent ecosystem: a library-first, transparent agent harness designed for developers who want full control, visibility, and simplicity.

Key Differentiators:

• Library-first - Embed in your applications, not locked into a CLI
• LLM-neutral - Choose your provider, your model, your cost model
• No hidden manipulation - All prompts visible, editable, configurable
• Static permissions - Deterministic boundaries, not runtime prompts
• Full transparency - Event-driven, everything inspectable

See docs/rationale.md for the full rationale and comparison with other solutions.

Features

Current Features:

• Chat loop - Interactive conversation with Ollama
• Tool calling - Structured tool execution with parameters
• read tool - Read file contents with guardrails
• list tool - Directory listing with pattern filtering
• write tool - Write files with overwrite protection
• update tool - Edit existing files with replace, insert, and delete operations
• search tool - Search file contents with regex or filenames with glob
• existence tool - Check if files or folders exist with security hardening
• mkdir tool - Create directories with recursive parent creation and depth limits
• git tool - Git operations (status, log, diff, branch, show) with permission-controlled commit/push
• web_search tool - Web search with SSRF protection, domain filtering, and rate limiting
• web_fetch tool - Fetch web content with SSRF protection, URL validation, and size limits
• agent tool - Spawn subagents with isolated context and recursion limits
• Slash commands - Built-in commands: /help, /think on|off
• Thinking mode - LLM reasoning trace with gray output
• Streaming - Real-time token streaming from Ollama
• Configuration - TOML-based configuration system
• Agent definitions - Load agents from Markdown files with YAML frontmatter
• Multiline input - Esc+Enter for newlines, Enter to submit
• Rich output - Styled terminal output with Rich
• Event-driven architecture - Library-first design with event emission
• Context persistence - Session resumption with JSONL storage
• Event logging - Full session replay capability
• Demo scripts - Generate documentation screenshots from Markdown scripts
• Update tool - Edit existing files with replace, insert, and delete operations

Planned Features:

• Guardrails - Tool parameter validation
• Permissions - Static TOML-based access control
• Multi-agent orchestration - Run coordinated agent teams
• Backend providers - OpenAI, Anthropic, custom backends
• Tool timing metrics - Performance tracking
• Token usage tracking - Cost monitoring
• Tool result caching - Reduce redundant calls
• Parallel tool execution - Concurrent read operations

Interactive Input

The interactive session supports:

• Multiline input: Press Esc+Enter to add newlines, Enter to submit
• Command history: Up/Down arrows navigate previous messages
• History search: Ctrl+R to search through history
• Keyboard navigation: Arrow keys, Ctrl+A/E for cursor positioning
• Text selection: Click and drag to select output, copy with Ctrl+Shift+C or Cmd+C

Slash Commands

Command	Description
/help	Show available commands
/think on|off	Enable/disable LLM thinking trace

Thinking Mode

When thinking is enabled, the LLM shows its reasoning process:

[Thinking]
Let me analyze this step by step...
First, I need to understand the file structure...

[Response]
Based on my analysis, here's what I found...

Demo Session Script

Generate terminal screenshots for documentation from Markdown script files:

# Run default demo script (demos/session.md)
python scripts/demo_session.py

# Run a specific demo script
python scripts/demo_session.py --script demos/list-tool.md

# Run all demo scripts in a directory
python scripts/demo_session.py --scripts-dir demos/

# Real LLM + log conversation for replay
python scripts/demo_session.py --script demos/session.md --log

# Replay from log (no LLM calls)
python scripts/demo_session.py --script demos/session.md --replay

# With an agent definition
python scripts/demo_session.py --script demos/session.md --agent examples/agents/markdown.md

Configuration

Yoker auto-discovers configuration files:

1. ./yoker.toml (current directory)
2. ~/.yoker.toml (user home directory)
3. Built-in defaults

# Zero-configuration startup - uses auto-discovered config
python -m yoker

Or create a yoker.toml file for explicit configuration:

[harness]
name = "my-yoke"
log_level = "INFO"

[backend]
provider = "ollama"

[backend.ollama]
base_url = "http://localhost:11434"
model = "llama3.2:latest"

[agents]
definition = "./agents/researcher.md"  # Optional: agent definition file

[tools.read]
enabled = true
allowed_extensions = [".txt", ".md", ".py"]

See examples/yoker.toml for the full configuration reference.

Architecture

Yoker uses an event-driven architecture for library-first design. The Agent emits events; application code handles UI.

Event Types: Session (start/end), Turn (start/end), Thinking (start/chunk/end), Content (start/chunk/end), Tool (call/result), Error, Command

Documentation

• Full documentation
• Installation guide
• Quick start
• Why Yoker? - Project rationale and comparison
• Architecture

Development

git clone https://github.com/christophevg/yoker.git
cd yoker
make setup    # Create virtual environment and install dependencies

make test     # Run tests with coverage
make check    # Type checking + linting
make docs     # Build documentation

Requires Python 3.10+. Uses uv for dependency management. See CLAUDE.md for project conventions.

Contributing

Contributions welcome! Please read CLAUDE.md for project conventions and development guidelines.

Changelog

See GitHub Releases for version history.

License

MIT License - see LICENSE for details.

---

Name: "yoker" - One who yokes. The agent noun from "yoke" (PIE yeug- meaning "to join"). Pairs with "clitic" (both are joining tools). See docs/NAME.md for full etymology.