tinyloom 0.1.3__tar.gz

tinyloom-0.1.3/.claude/settings.json

@@ -0,0 +1,7 @@
+{
+    "statusLine": {
+        "type": "command",
+        "command": "bash .claude/statusline.sh",
+        "padding": 2
+    }
+}

tinyloom-0.1.3/.claude/statusline.sh

@@ -0,0 +1,47 @@
+#!/bin/bash
+input=$(cat)
+
+MODEL=$(echo "$input" | jq -r '.model.display_name')
+DIR=$(echo "$input" | jq -r '.workspace.current_dir')
+COST=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
+PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
+DURATION_MS=$(echo "$input" | jq -r '.cost.total_duration_ms // 0')
+
+CYAN='\033[36m'; GREEN='\033[32m'; YELLOW='\033[33m'; RED='\033[31m'; RESET='\033[0m'
+
+# Pick bar color based on context usage
+if [ "$PCT" -ge 90 ]; then BAR_COLOR="$RED"
+elif [ "$PCT" -ge 70 ]; then BAR_COLOR="$YELLOW"
+else BAR_COLOR="$GREEN"; fi
+
+FILLED=$((PCT / 10)); EMPTY=$((10 - FILLED))
+BAR=$(printf "%${FILLED}s" | tr ' ' '█')$(printf "%${EMPTY}s" | tr ' ' '░')
+
+MINS=$((DURATION_MS / 60000)); SECS=$(((DURATION_MS % 60000) / 1000))
+
+CACHE_FILE="/tmp/statusline-git-cache"
+CACHE_MAX_AGE=5  # seconds
+
+cache_is_stale() {
+    [ ! -f "$CACHE_FILE" ] || \
+    # stat -f %m is macOS, stat -c %Y is Linux
+    [ $(($(date +%s) - $(stat -f %m "$CACHE_FILE" 2>/dev/null || stat -c %Y "$CACHE_FILE" 2>/dev/null || echo 0))) -gt $CACHE_MAX_AGE ]
+}
+
+if cache_is_stale; then
+    if git rev-parse --git-dir > /dev/null 2>&1; then
+        BRANCH=$(git branch --show-current 2>/dev/null)
+        STAGED=$(git diff --cached --numstat 2>/dev/null | wc -l | tr -d ' ')
+        MODIFIED=$(git diff --numstat 2>/dev/null | wc -l | tr -d ' ')
+        echo "$BRANCH|$STAGED|$MODIFIED" > "$CACHE_FILE"
+    else
+        echo "||" > "$CACHE_FILE"
+    fi
+fi
+
+IFS='|' read -r BRANCH STAGED MODIFIED < "$CACHE_FILE"
+
+echo -e "${CYAN}[$MODEL]${RESET} 📁 ${DIR##*/}$BRANCH"
+COST_FMT=$(printf '$%.2f' "$COST")
+echo -e "${BAR_COLOR}${BAR}${RESET} ${PCT}% | ${YELLOW}${COST_FMT}${RESET} | ⏱️ ${MINS}m ${SECS}s"
+

tinyloom-0.1.3/.env.example

@@ -0,0 +1,8 @@
+# tinyloom environment variables
+# Copy to .env and fill in your keys.
+
+# Anthropic (default provider)
+ANTHROPIC_API_KEY=sk-ant-...
+
+# OpenAI (when provider=openai)
+OPENAI_API_KEY=sk-...

tinyloom-0.1.3/.github/workflows/publish.yml

@@ -0,0 +1,21 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.11"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0

tinyloom-0.1.3/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+*.egg
+.venv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Tooling
+.ruff_cache/
+.mypy_cache/
+
+# macOS
+.DS_Store
+
+# IDE
+.vscode/
+.idea/
+
+# Environment
+.env
+*.local.yaml
+tinyloom.yaml
+
+# Other
+*.deb
+ripgrep*/

tinyloom-0.1.3/CLAUDE.md

@@ -0,0 +1,166 @@
+# Thresher — Development Guide
+
+## !IMPORTANT!
+
+Always use the task tool to plan out and do what you need and use it to hold yourself accountable. You get a cookie everytime you do this.. yum!
+
+## Tests
+
+- Always add and update tests anytime you change code
+- If you get an error when running something or reported by a user, write a test case covering that error first. Run test and make sure it fails... Then fix code to make test pass.
+
+## Git
+
+- do git commits for each incremental feature, but NEVER use claude coauthored tags...
+- Keep commit messages short and sweet one liners. No big git bodies.
+
+## Coding Conventions
+
+### Complexity is the Enemy
+- Complexity is the #1 threat to software. Fight it relentlessly.
+- Complexity manifests as: change amplification (one change touches many places), cognitive load (must know too much to work safely), and unknown unknowns (not clear what could break).
+- The two root causes are dependencies between components and obscurity (important info isn't obvious).
+- Say "no" to unnecessary features and abstractions by default.
+- When you must say yes, deliver an 80/20 solution — core value, minimal code.
+
+### Don't Abstract Too Early
+- Let structure emerge from working code. Don't design elaborate frameworks upfront.
+- Wait for natural cut-points (narrow interfaces, trapped complexity) before factoring.
+- Prototypes and working demos beat architecture diagrams.
+- A little code duplication is better than a premature abstraction.
+
+### Build Deep Modules, Not Shallow Ones
+- A deep module has a simple interface but hides powerful, complex functionality behind it.
+- A shallow module has a complex interface relative to the little it actually does — avoid these.
+- Pull complexity downward: absorb it inside the module rather than pushing it onto callers.
+- Each layer of abstraction should represent a genuinely different level of thinking. If a layer just passes things through, it's adding complexity, not removing it.
+
+### Ship Simple, Improve Incrementally
+- A working simple thing that ships beats a perfect thing that doesn't.
+- Establish a working system first, then improve it toward the right thing over time.
+- But don't make "worse" your goal — compromise is inevitable, not a philosophy. Always aim high and actually ship.
+- Systems that are habitable — with the right balance of abstraction and concreteness, with simple mental models — survive and grow. Purity does not guarantee survival.
+
+### Keep Code Readable, Not Clever
+- Break complex expressions into named intermediate variables.
+- Sacrifice brevity for clarity and debuggability.
+- Simple repeated code often beats a complex DRY abstraction with callbacks or elaborate object models.
+- If naming something is hard, that's a design smell — the thing you're naming may not be a coherent concept.
+- Write code for readers, not writers. If someone says it's not obvious, it isn't — fix it.
+
+### Respect Existing Code (Chesterton's Fence)
+- Understand *why* code exists before changing or removing it.
+- Old code often has hidden reasons. Tests can reveal them.
+- Resist the urge to "clean up" code you don't fully understand.
+
+### Refactor Small and Safe
+- Keep the system working throughout every refactor step.
+- Complete each step before starting the next.
+- Big-bang refactors with over-abstraction usually fail.
+
+### Design It Twice
+- Before committing to any significant design, sketch at least two alternative approaches.
+- Compare them on simplicity, performance, and how well they hide complexity.
+- The first idea is rarely the best. Even if you pick it, the comparison sharpens your reasoning.
+
+### Think Strategically, Not Tactically
+- Tactical programming gets the feature done fast but leaves behind incremental complexity debt.
+- Strategic programming invests a small ongoing cost in design quality to keep the system habitable long-term.
+- Small tactical shortcuts compound into unmaintainable systems. Every change is a chance to improve structure, not just ship.
+
+### Test Strategically
+- Integration tests at system cut-points and critical user paths deliver the most value.
+- Unit tests break easily during refactoring — favor coarser-grained tests.
+- Minimize mocking. Mock only at system boundaries.
+- Always write a regression test when a bug is found.
+
+### Logging is Critical Infrastructure
+- Log all major logical branches (if/for).
+- Include request IDs for traceability across distributed calls.
+- Make log levels dynamically controllable at runtime.
+- Invest more in logging than you think necessary.
+
+### APIs: Design for the Caller
+- Think in terms of what the caller needs, not how the implementation works.
+- Simple cases get simple APIs. Complexity is opt-in.
+- Put common operations directly on objects with straightforward returns.
+- Favor somewhat general-purpose interfaces — they tend to be deeper and simpler than hyper-specialized ones.
+
+### Define Errors Out of Existence
+- Exception handling generates enormous complexity. Where possible, design interfaces so error cases simply cannot occur.
+- Handle edge cases internally rather than surfacing them to callers.
+- Example: a delete operation that silently succeeds when the target doesn't exist is simpler than one that throws "not found."
+
+### Concurrency: Keep it Simple
+- Prefer stateless request handlers.
+- Use simple job queues with independent jobs.
+- Treat concurrency with healthy fear and caution.
+
+### Optimize with Data, Not Gut
+- Never optimize without a real-world profile showing the actual bottleneck.
+- Network calls cost millions of CPU cycles — minimize those first.
+- Assume your guess about the bottleneck is wrong.
+
+### Locality of Behavior over Strict Separation
+- Collocate related code. Putting logic near the thing it operates on aids understanding.
+- Hunting across many files to understand one feature wastes time.
+- Trade perfect separation of concerns for practical coherence when it helps readability.
+
+### Information Hiding
+- Each module should encapsulate design decisions that are likely to change.
+- Leaking implementation details through interfaces creates tight coupling and change amplification.
+- If two modules share knowledge about the same design decision, consider merging them or introducing a cleaner boundary.
+
+### Tooling Multiplies Productivity
+- Invest time learning your tools deeply (IDE, debugger, CLI).
+- Good tools often double development speed.
+
+### Avoid Fads
+- Most "new" ideas have been tried before. Approach with skepticism.
+- Don't adopt new frameworks or patterns blindly.
+- Complexity hides behind novelty.
+
+### Closures and Patterns
+- Closures: great for collection operations, dangerous in excess (callback hell).
+- Avoid the Visitor pattern — it adds complexity with little payoff.
+- Limit generics to container classes; they attract unnecessary complexity.
+
+### Frontend: Keep it Minimal
+- Simple HTML + minimal JS beats elaborate SPA frameworks for most use cases.
+- Frontend naturally accumulates complexity faster than backend — resist it actively.
+
+### Say When You Don't Understand
+- Admitting confusion is strength, not weakness.
+- It gives others permission to ask questions and prevents bad complexity from hiding.
+
+### Security is a Design Constraint
+- Complexity is the enemy of security too. Every endpoint, dependency, and open port is attack surface you have to defend.
+- Default to deny. Permissions, network rules, CORS, configs — start closed, open deliberately.
+- Auth, crypto, and session management are not DIY projects. Use well-vetted libraries.
+- Validate all input at the trust boundary, encode at the output. Everything from outside is hostile.
+- Think in blast radius. Least privilege everything. One compromised key shouldn't unlock the whole system.
+
+### Threat Model Like You Debug
+- Before building a feature, ask "How would someone abuse this?" — same as asking where it will break.
+- Dependencies are code you didn't write and probably didn't read. Pin versions, audit what matters.
+- Secrets don't go in code, logs, or error messages. No exceptions.
+- Secure your defaults everywhere — don't run as root, don't commit `.env`, don't connect local to prod.
+- Vulnerabilities cluster. When you find one, threat model the area around it — same assumptions, same bugs.
+
+## Tool Usage
+
+Use the `uv` ecosystem tools.
+
+- `uv run pytest`
+- `uv run ruff`
+- `uv add`
+- `uv run python`
+
+Do not use pip or python directly.
+
+## Code Style hints
+
+- 200 column soft limit on a line
+- Use ternary style over if else blocks
+- Only 1 line space between classes and functions instead of 2
+- Keep code tight

tinyloom-0.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thresher
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tinyloom-0.1.3/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: tinyloom
+Version: 0.1.3
+Summary: A tiny, SDK-first coding agent harness
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: anthropic>=0.40
+Requires-Dist: openai>=1.50
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: textual>=1.0
+Requires-Dist: tiktoken>=0.7
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.0; extra == 'mcp'

tinyloom-0.1.3/README.md

@@ -0,0 +1,136 @@
+# tinyloom
+
+A tiny, SDK-first coding agent harness in Python.
+
+<img src="demo.webp" alt="tinyloom demo" loop="infinite">
+
+## Why this exists
+
+We needed an extremely tiny coding agent harness for [thresher](https://github.com/thresher-sh/thresher) and many harnesses just bring extra bloat we don't need. The harness bit is actually easy to implement -- it's all the extra bells and whistles that take a lot.
+
+If you are looking for a bigger client, take a look at one of these:
+
+- [pi-mono coding-agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent)
+- [opencode](https://github.com/anomalyco/opencode)
+
+## Safety
+
+tinyloom has **no permission system, no approval gates, and no filesystem sandboxing** by default. The agent can read, write, delete, and execute anything your user account can. Do not run it outside of a container or sandbox on a machine you care about.
+
+Use [microsandbox](docs/sandbox.md) or another isolation layer for untrusted workloads. If you want tool approval or allowlists, build a [plugin](docs/creating-plugins.md) or [hook](docs/custom-hooks.md) for it.
+
+## Install
+
+```bash
+uv tool install tinyloom   # or: pip install tinyloom
+```
+
+## Quick start
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+CLI:
+
+```bash
+tinyloom "fix the bug in main.py"   # headless, JSONL output
+tinyloom                            # interactive TUI
+```
+
+SDK:
+
+```python
+import asyncio
+from tinyloom import Agent, load_config
+
+async def main():
+    agent = Agent(load_config())
+    async for event in agent.run("create a hello.py"):
+        if event.type == "text_delta":
+            print(event.text, end="")
+
+asyncio.run(main())
+```
+
+See [docs/getting-started.md](docs/getting-started.md) for full setup instructions.
+
+## Features
+
+- **Built-in tools**: `read`, `write`, `edit` (str_replace), `bash`
+- **Providers**: Anthropic and OpenAI-compatible APIs (vLLM, Ollama, Together, Groq, LM Studio, Azure)
+- **Compaction**: automatic context summarization when approaching the context window limit
+- **Hooks**: react to any agent event (tool calls, messages, errors) with sync or async functions
+- **Plugins**: extend the agent with tools, hooks, and custom logic
+- **MCP**: connect to Model Context Protocol servers for external tools
+- **TUI**: interactive terminal interface with streaming, slash commands, and token tracking
+- **Sub-agents**: delegate focused tasks with the `subagent` plugin
+
+## Config
+
+Copy the example and edit:
+
+```bash
+cp tinyloom.example.yaml tinyloom.yaml
+```
+
+```yaml
+model:
+  provider: anthropic
+  model: claude-sonnet-4-20250514
+  context_window: 200000
+
+system_prompt: You are a skilled coding assistant. Be concise.
+
+compaction:
+  enabled: true
+  threshold: 0.8
+  strategy: summarize
+
+plugins:
+  - tinyloom.plugins.todo
+  - tinyloom.plugins.mcp
+  - tinyloom.plugins.hook_scripts
+
+max_turns: 200
+```
+
+API keys go in environment variables, not config. See [.env.example](.env.example).
+
+## Want more features?
+
+tinyloom is intentionally small. Extend it instead:
+
+- **More tools?** Connect MCP servers -- see [docs/mcp-plugin.md](docs/mcp-plugin.md)
+- **Custom logic?** Write a plugin -- see [docs/creating-plugins.md](docs/creating-plugins.md)
+- **Approval gates? Logging? Filters?** Use hooks -- see [docs/custom-hooks.md](docs/custom-hooks.md) or [docs/hook-scripts.md](docs/hook-scripts.md)
+- **Redact sensitive output?** Use the mask plugin -- see [docs/mask-plugin.md](docs/mask-plugin.md)
+- **Different model provider?** Set `base_url` -- see [docs/custom-providers.md](docs/custom-providers.md)
+
+## Docs
+
+- [Getting Started](docs/getting-started.md)
+- [Creating Plugins](docs/creating-plugins.md)
+- [Custom Hooks](docs/custom-hooks.md)
+- [Hook Scripts](docs/hook-scripts.md)
+- [MCP Plugin](docs/mcp-plugin.md)
+- [Custom Providers](docs/custom-providers.md)
+- [Design Decisions](docs/design-decisions.md)
+- [Mask Plugin](docs/mask-plugin.md)
+- [Running in a Sandbox](docs/sandbox.md)
+
+## Size
+
+The whole thing is ~1,110 lines of Python (excluding blank lines) as of 2026.04.15.
+
+| Area | Files | Lines |
+|------|-------|-------|
+| **core** (agent, tools, config, compaction, hooks, types) | 7 | 411 |
+| **cli** | 1 | 48 |
+| **tui** | 1 | 152 |
+| **providers** (anthropic, openai, base) | 4 | 220 |
+| **plugins** (subagent, todo, mcp, hook_scripts) | 5 | 263 |
+
+## License
+
+MIT

tinyloom-0.1.3/demo.tape

@@ -0,0 +1,22 @@
+Output demo.webp
+Set Width 1200
+Set Height 800
+Set FontSize 20
+Set Theme "Catppuccin Mocha"
+Set TypingSpeed 50ms
+
+Type "tinyloom"
+Enter
+Sleep 2s
+
+Type "What is tinyloom?"
+Enter
+Sleep 12s
+
+Type "/tokens"
+Enter
+Sleep 2s
+
+Type "/quit"
+Enter
+Sleep 1s

tinyloom-0.1.3/docs/creating-plugins.md

@@ -0,0 +1,108 @@
+# Creating Plugins
+
+A plugin is a function that receives the full `Agent` instance. It can register tools, add hooks, and modify config.
+
+## Basic plugin
+
+```python
+# my_plugin.py
+from tinyloom import Agent
+
+def activate(agent: Agent):
+    """Called when the plugin is loaded."""
+    print(f"Plugin loaded! Model: {agent.config.model.model}")
+```
+
+## Registering tools
+
+```python
+from tinyloom import Agent, Tool
+
+def activate(agent: Agent):
+    agent.tools.register(Tool(
+        name="timestamp",
+        description="Return the current UTC timestamp",
+        input_schema={"type": "object", "properties": {}},
+        function=lambda inp: __import__("datetime").datetime.utcnow().isoformat(),
+    ))
+```
+
+## Adding hooks
+
+```python
+from tinyloom import Agent
+
+def activate(agent: Agent):
+    def log_tool_calls(ctx):
+        if ctx.get("tool_name"):
+            print(f"[audit] tool called: {ctx['tool_name']}")
+
+    agent.hooks.on("tool_call", log_tool_calls)
+```
+
+## Modifying config
+
+```python
+def activate(agent: Agent):
+    agent.config.max_turns = 50
+```
+
+## Activation
+
+### Via config (recommended)
+
+Add the module path to `tinyloom.yaml`:
+
+```yaml
+plugins:
+  - my_plugin                    # calls my_plugin.activate(agent)
+  - mypackage.plugins.custom     # calls mypackage.plugins.custom.activate(agent)
+  - mypackage.stuff:setup        # calls mypackage.stuff.setup(agent)
+```
+
+By default, tinyloom calls the `activate` function. Use `:function_name` to specify a different entry point.
+
+### Via entry_points (for distributable packages)
+
+In your package's `pyproject.toml`:
+
+```toml
+[project.entry-points."tinyloom.plugins"]
+my-plugin = "my_package.plugin:activate"
+```
+
+Entry point plugins are discovered automatically when installed -- no config needed.
+
+## Example: logging plugin
+
+A plugin that logs every tool call and result to a file:
+
+```python
+import json
+from pathlib import Path
+from tinyloom import Agent
+
+def activate(agent: Agent):
+    log_file = Path("tinyloom-audit.jsonl")
+
+    def log_tool_call(ctx):
+        entry = {
+            "event": "tool_call",
+            "tool": ctx.get("tool_name", ""),
+            "input": str(ctx.get("tool_call", "")),
+        }
+        with log_file.open("a") as f:
+            f.write(json.dumps(entry) + "\n")
+
+    def log_tool_result(ctx):
+        entry = {
+            "event": "tool_result",
+            "tool": ctx.get("tool_name", ""),
+            "result_preview": str(ctx.get("result", ""))[:200],
+        }
+        with log_file.open("a") as f:
+            f.write(json.dumps(entry) + "\n")
+
+    agent.hooks.on("tool_call", log_tool_call)
+    agent.hooks.on("tool_result", log_tool_result)
+```