Metadata-Version: 2.4
Name: binsmith
Version: 0.5.0
Summary: Binsmith agent plugin for Lattis
Project-URL: Homepage, https://github.com/caesarnine/binsmith
Project-URL: Repository, https://github.com/caesarnine/binsmith
Project-URL: Issues, https://github.com/caesarnine/binsmith/issues
License-Expression: MIT
Keywords: agent,ai,automation,cli,tools
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.12
Requires-Dist: lattis>=0.5.0
Requires-Dist: logfire>=3.0.0
Description-Content-Type: text/markdown

# Binsmith

A Lattis agent that accumulates small CLI tools in a persistent workspace.

Most chat-style agents are “stateless” in the sense that they don’t leave behind reusable artifacts. Binsmith is configured to turn repeated work into scripts and keep them under `.lattis/workspace/bin`, so later tasks can compose existing tools instead of re-solving the same problem.

Binsmith is distributed as a [Lattis](https://github.com/caesarnine/lattis) plugin.

## Quick start

```bash
export GOOGLE_API_KEY=... # see below for other providers
uvx binsmith
```

This starts the TUI with Binsmith as the default agent. To run a server for remote access:

```bash
uvx binsmith server
# Then open http://localhost:8000
```

Or run via Lattis alongside other agents:

```bash
uv pip install binsmith
uvx lattis --agent binsmith
```

## What it does

Binsmith is an agent prompt + a workspace.

- It runs commands using a single tool: **`bash`**
- Your project workspace has `workspace/bin` on the PATH
- When a task is worth repeating, it writes a script into `workspace/bin`
- Those scripts persist across sessions and can call each other (Unix-style)
- It can symlink tools into a user-writable bin directory on your PATH (see Configuration)

Over time you end up with a small toolkit of scripts you and the agent can both use.

Example (tools invented over time; names illustrative):

```bash
fetch-url https://news.ycombinator.com | html2md | summarize --bullets
brief
todo add "Review PR #42"
```

## Workspace layout

```text
.lattis/
  workspace/
    bin/      # Scripts Binsmith creates (persists across sessions)
    data/     # Persistent data files
    tmp/      # Scratch space
```

## Script format

Scripts are intended to be standalone and “git-friendly”. Python scripts use `uv` inline metadata so dependencies are declared in the file:

```python
#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.12"
# dependencies = ["httpx"]
# ///
"""Fetch a URL and extract text content."""
```

## Tool conventions

Binsmith is prompted to keep tools composable and discoverable:

- Prefer stdin/stdout for data flow
- Produce clean text output by default
- Support `--json` when machine-readable output makes sense
- Support `--help` and optionally `--describe`
- Exit `0` on success, non-zero on failure
- Reuse or extend existing tools instead of creating near-duplicates

The point is to make workflows like `fetch-url | html2md | summarize` viable.

## How it works (mechanics)

Binsmith is “just” an agent configuration:

- It can run shell commands inside the project directory
- It can see what’s already in `.lattis/workspace/bin`
- It is instructed to:
  1. use existing scripts when possible
  2. write scripts when you hit repetition
  3. improve existing scripts rather than cloning variants

Lattis handles the server, UIs, thread persistence, and session state.

## Remote usage

A common setup is to run the server on a machine that stays up and connect from anywhere:

```bash
# On the server
uvx binsmith server --host 0.0.0.0

# From a client machine
uvx binsmith --server http://your-server:8000
```

(If you bind to a public interface, keep it on a private network / VPN.)

## TUI commands

```text
/help                     Show help
/threads                  List threads
/thread <id>              Switch to thread
/thread new [id]          Create new thread
/thread delete <id>       Delete thread
/clear                    Clear current thread
/model                    Show current model
/model list [filter]      List models
/model set <name>         Set model
/quit                     Exit
```

## Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `BINSMITH_MODEL` | `google-gla:gemini-2.0-flash` | Default model |
| `BINSMITH_LOGFIRE` | `0` | Enable Logfire telemetry |
| `BINSMITH_LINK_BINS` | `1` | Link tools into a writable PATH directory |
| `BINSMITH_BIN_DIR` | | Override the link directory (should be on your PATH) |

Binsmith only links tools when it can find a writable PATH directory under your home folder, and it skips names
that already resolve on PATH to avoid shadowing existing commands. Set `BINSMITH_BIN_DIR` to control the link
location when you want a specific directory.

Lattis configuration (`LATTIS_*`) controls storage and server settings.

## Requirements

- Python 3.12+
- [uv](https://docs.astral.sh/uv/)
- An API key for at least one model provider

```bash
export GOOGLE_API_KEY=...     # Google
export ANTHROPIC_API_KEY=...  # Anthropic
export OPENAI_API_KEY=...     # OpenAI
```

## Why the name

It forges tools into `bin/`.
