A local endpoint
Send requests to 127.0.0.1:7878 through bram’s CLI or HTTP API. A named peer selects the command that answers.
Open-source developer tool · Starlit Digital
bram
bram routes prompts between local AI tools.
One small daemon on your Mac gives your scripts a common way to call configured command-line AI tools—and hands back structured results you can program against.
No model included. No account needed. Nothing to configure to try the built-in echo peer.
Why bram?
Change tools.
Keep your script’s interface.
AI command-line tools use different arguments and output formats. bram sits between your scripts and those tools: one local address, one response envelope. Choose another configured peer without changing how your script calls bram.
Results you can use
Get peer, output, exit_code and duration_ms, plus stderr when present. Tool output remains text; bram does not interpret the model’s answer.
Explicit adapters
Configure the command, arguments and timeout for each peer. Commands must accept prompts on stdin; tools with another interface need a wrapper.
Running in a minute
Install. Echo. Connect.
With Go 1.24.0 or later installed, start with a local echo. It needs no account or AI provider. Go installs the CLI into GOBIN, or $(go env GOPATH)/bin; add that directory to PATH.
Install the CLI
git clone --branch v0.2.0 --depth 1 https://github.com/Starlit-Digital/bram.git
cd bram
go install ./cmd/bramThis installs bram only. Build from source for the mailbox helper and user-local service installation.
Start with zero setup
Run bram daemon in one terminal, then bram ask --peer echo "hello from bram" in another. With no existing config file, the built-in /bin/cat peer answers.
Configure a peer
bram sample-config prints an example. Save your reviewed config, add a trusted peer and restart the daemon. After the source install with make build, bram launchd install starts the background service.
What is a peer?
A command with a simple contract.
A peer is a command that reads a prompt on stdin and writes its answer on stdout.
This runnable config keeps echo as the default and adds a helper peer using the same local command. Replace the helper’s command and arguments with your trusted adapter.
Save it to ~/.config/bram/config.json, or $XDG_CONFIG_HOME/bram/config.json when set. sample-config prints JSON; it does not save a file.
{
"listen": "127.0.0.1:7878",
"default_peer": "echo",
"peers": {
"echo": {
"command": "/bin/cat",
"timeout": "10s"
},
"helper": {
"command": "/bin/cat",
"args": [],
"timeout": "2m"
}
}
}Call it over HTTP
One request.
A structured result.
GET /v1/health and GET /v1/peers let you inspect the daemon. POST /v1/ask sends a prompt to a peer.
Failures return JSON too: 400 for a bad request, 404 for an unknown peer, and 502 for a peer execution failure. Elapsed time varies; empty stderr is omitted.
curl -s http://127.0.0.1:7878/v1/ask \
-H 'content-type: application/json' \
-d '{"peer":"echo","prompt":"hello from bram"}'
# Example response; timing varies:
{
"peer": "echo",
"output": "hello from bram",
"exit_code": 0,
"duration_ms": 2
}The Grok helper
A file drop for tools
that need a responder.
bram’s bundled grok helper writes your prompt to a folder and waits for a responder to write the answer back. It is a mailbox wrapper, not an official Grok integration. You supply the responder; real-provider qualification remains open.
The full source install includes this helper and replaces any existing command named grok in the selected prefix, retaining a backup. The Go-only install does not include it. Read the installation notes before installing.
Keep it local
Trust the commands
you configure.
The API has no password. Keep it on 127.0.0.1; loopback does not isolate other users or processes on your machine. Peer commands run with your privileges, can reach the network and can incur provider charges.
Plaintext mailboxPrompts and responses remain on disk. Restrict mailbox access; bram does not remove those files automatically.
Current limitsNo API authentication, request/output size limits or concurrency controls. Use trusted commands and modest requests. This is early-development software.
Evidence with a scopemacOS Go tests, isolated HTTP/CLI echo, temporary installation and mock mailbox checks passed for 0.2.0. Real AI providers and native Linux/Windows workflows are not qualified.
Read the security policy before use.