paper-instruments / feather-train

# Feather
Feather is a lightweight agent harness for knowledge work, with tools and skills
for documents, spreadsheets, presentations, and PDFs. Use it locally with an
OpenAI-compatible model, evaluate it on Harbor tasks, or integrate its rollouts
with model training.
## Packages
| Package | Purpose |
| --- | --- |
| Feather Harness | Agent loop, file and shell tools, Paper document skills, context compaction, and a local CLI. Includes two built-in harness profiles: **`prod`** (default), with professional guidance and image support; and **`train`**, with minimal prompts and original skill guidance for training. |
| Feather Train | Rollouts and grading on snapshotted E2B worlds, Braintrust logging, and a reference Tinker training integration through Verifiers. |
| Feather Eval | Run Feather on Harbor tasks and export trajectories in Harbor's ATIF format. |
Each package is independently installable and publishable. A shared `uv` workspace
manages their development dependencies and lockfile.
## Run Feather locally
The installer supports macOS and Linux and requires Bash, curl, and
Git. Install with:
 [code] 
To install from a local checkout, run from its root:
 [code] 
The installer provisions its own uv and Python 3.12, then installs the CLI, Paper
document packages, PDF libraries, and data libraries into a dedicated Feather virtual environment
under `~/.local/share/feather/`. It does not install Python packages into your
current directory, active environment, or system Python. The launcher at
`~/.local/bin/feather` sets the execution environment so the model's `python` and
`python3` shell commands use those installed packages by default. No activation is needed.
If `~/.local/bin` is not on your `PATH`, invoke `~/.local/bin/feather` directly or
add that directory to `PATH` yourself; the installer does not edit shell profiles.
Install ripgrep separately; PDF rendering needs Poppler, and spreadsheet
recalculation needs LibreOffice. See Harness setup
for system packages and installation options. Then run:
 [code] 
Put your input files in `workspace/`. `run.json` contains the final answer and the
agent's execution trace. The model identifier and endpoint come from your provider;
omit `--base-url` for the OpenAI client's default endpoint. Shell tools run with
your OS permissions. Running Feather creates skill and log directories inside the
selected workspace.
To use a project's Python for task commands, pass
`--python /absolute/path/to/project/.venv/bin/python` or set `python` in the JSON
configuration. Feather keeps its own runtime environment. Task shell commands
can use `"$FEATHER_PYTHON"` to access the bundled Paper packages. See
task Python selection for examples.
For evaluation, follow the Harbor example.
For training, start with Feather Train: it takes task
datasets and prepared E2B snapshots as inputs.
## Use the packages from another repository
Pin the packages you use to the same full Git commit. For a uv-managed consumer,
keep package depende