rec README

The project's README from github.com/recursive-oss/rec. As one markdown file: README.md.

Recursive

rec is our custom inference engine for running Recursive's language models locally on your machine. It provides lightning-fast inference for single-session usage. Compared to llama.cpp, rec delivers 1.4–2.6× the token throughput across the context lengths shown below on M4 Pro. Use it with pi, OpenCode, or connect your own client through the local API.

Flint decode throughput: rec vs. llama.cpp at context lengths from 1K to 252K tokens

Flint on Apple M4 Pro (48 GB), 4-bit weights, 1K–252K-token prompts and 1,024 output tokens. Five runs per context; prefill excluded.

Requirements

Install

Install using:

curl -fsSL https://raw.githubusercontent.com/recursive-oss/rec/main/install.sh | bash

This installs rec in ~/.local/bin and adds it to your PATH for new terminals. All other data lives under ~/.local/share/rec.

Usage

We find the best performance from our models when paired with the pi harness. For convenience, rec provides pre-configured recipes for running pi and OpenCode harnesses. Run them using:

rec launch pi  # preferred
rec launch opencode

⚠️ rec is optimized for single-session usage. To run multiple agents at a time, see our documentation for other ways to run our models.

This starts our inference server and connects to it automatically. The first run downloads the model and harness. The model server continues to run after you close the terminal. Run rec stop to stop it.

These harnesses are kept separate from anything on your system. Use rec exec pi|opencode ARGS to run their own commands, for example:

rec exec pi install npm:PACKAGE

Use your own harness

rec exposes OpenAI and Anthropic-compatible chat-completion APIs. Start the server:

rec serve

Keep this terminal open. When flint is ready. appears, connect a client from another terminal.

To use your own install of pi or OpenCode, run:

rec launch --args pi
rec launch --args opencode

Each command prints the environment and command line that rec launch uses, instead of running it. Replace the harness path with the path to your own harness. The command also points the harness at rec's own settings and sessions; remove those variables to keep yours.

To send a request directly to the OpenAI-compatible API:

curl -fsS http://127.0.0.1:11500/v1/chat/completions \
  -H "Authorization: Bearer $(rec auth token)" \
  -H 'Content-Type: application/json' \
  -d '{"model":"flint","messages":[{"role":"user","content":"Say hello."}],"max_tokens":128}'

The response contains generated text in choices. For other clients, use base URL http://127.0.0.1:11500/v1, model flint, and the API key from rec auth token.

The Anthropic-compatible API is available at http://127.0.0.1:11500/v1/messages. Point ANTHROPIC_BASE_URL at http://127.0.0.1:11500 and send the token from rec auth token as a bearer token or as x-api-key. The model is flint.

Commands

Command What it does
rec launch pi|opencode Start the server if needed and open a harness
rec exec pi|opencode ARGS Run a harness command, such as installing a plugin
rec serve Start the model server in this terminal
rec status Show whether the server is running
rec stop Stop the server
rec auth token Print the local API key
rec pull Download the model without starting the server
rec doctor Check your hardware and installation
rec update Update rec to the latest release
rec uninstall Remove rec, its models and its settings

Run rec COMMAND --help for a command's options.

Help and contributing

rec (recursive-oss/rec)

Searching Database…

229 ·GitHub
Rec
What is this?rec is Recursive's custom inference engine for running their language models locally on your Mac, tuned for fast single-session use.
Is this a CLI tool or a background service?It is a command-line tool: you install the rec binary and run it from the terminal, where it starts a local model server you connect a harness or your own client to.
How do I install and start rec?Run the install command, which places rec in ~/.local/bin and adds it to your PATH, then launch it with 'rec launch pi' or 'rec launch opencode' to start the server and open a harness.
What hardware and software do I need?An Apple Silicon Mac with an M4 Pro, M4 Max, M5 Pro, or M5 Max chip, at least 48 GB of unified memory, about 30 GB of free disk space, and Node.js 22 with npm if you want to use the pi harness.
Can I run multiple agent sessions at once?No, rec is built for single-session usage; running several agents at the same time needs a different setup described in rec's separate documentation.
Will this run on any Mac?No, only on specific recent Apple Silicon chips (M4 Pro/Max or M5 Pro/Max) with at least 48 GB unified memory; lower-spec or Intel Macs aren't supported.
Does it need an internet connection to run?Only the first run needs internet, to download the model and harness; after that, inference runs fully locally on your machine.
What is flint?flint is the language model that ships with rec, the model name you point your API client at when connecting to rec's local OpenAI- or Anthropic-compatible server.
How much faster is rec than llama.cpp?On an Apple M4 Pro with 4-bit weights, rec delivers 1.4-2.6x the token throughput of llama.cpp across context lengths from 1K to 252K tokens.
Can I connect my own coding agent instead of pi or OpenCode?Yes, rec exposes OpenAI- and Anthropic-compatible chat-completion APIs, so any compatible client or your own harness install can connect via rec's local server using the token from 'rec auth token'.
What are similar projects?public-apis, free-programming-books, system-design-primer, developer-roadmap, awesome-python, project-based-learning, hermes-agent, Python
Which topics is it in?python
Creator
recursive-oss
Size
0.2 MB
Stars
229
Updated
CommitOct 27Releasev0.1.1Oct 26
Age
5d
Commits · 90 Days