- Python 90.1%
- Rust 9.4%
- Shell 0.5%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
Bumps [certifi](https://github.com/certifi/python-certifi) from 2026.7.22 to 2026.10.18. - [Commits](https://github.com/certifi/python-certifi/compare/2026.07.22...2026.10.18) --- updated-dependencies: - dependency-name: certifi dependency-version: 2026.10.18 dependency-type: indirect ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> |
||
| .github | ||
| dyad-mapping | ||
| src/ultra_ralph_local | ||
| tests | ||
| .gitignore | ||
| CODE_OF_CONDUCT.md | ||
| CONTRIBUTING.md | ||
| LICENSE | ||
| pyproject.toml | ||
| README.md | ||
| SECURITY.md | ||
| start_ralph_loop.sh | ||
| uv.lock | ||
| workspace.txt | ||
ultra-ralph-local
Public uvx CLI for running a small recursive Ralph council against OpenRouter, appending the winning decision to a hash-chained decisions.log, and optionally uploading that log to Hugging Face.
By default, uploads target:
- dataset repo:
PeetPedro/ultrawhale-dogfood - dataset path:
ralph/decisions.log
You can keep those defaults or override them during first-run setup.
What it does
Each run:
- snapshots the workspace
- optionally reads
workspace.txt - optionally reads a local
dyad-mapping/checkout frompeterlodri-sec/dyad-mapping - asks a small council of Ralphs for the next decision
- appends the winning decision to
decisions.log - optionally uploads
decisions.logto Hugging Face
Requirements
- Python 3.11+
uvforuvx- an OpenRouter API key
- optional: a Hugging Face token if you want uploads
Quick start
Run the setup flow:
uvx --from git+https://github.com/8b-is/ultra-ralph-local ultra-ralph-local setup
The setup prints the exact config path it writes to.
Typical locations:
- macOS:
~/Library/Application Support/ultra-ralph-local/config.json - Linux:
~/.config/ultra-ralph-local/config.json - Windows: platformdirs user config directory for
ultra-ralph-local
It asks for:
OPENROUTER_API_KEY(required)HF_TOKEN(optional)- Hugging Face dataset repo, default
PeetPedro/ultrawhale-dogfood - dataset path, default
ralph/decisions.log - whether uploads should be enabled by default
Then run one iteration in the current directory:
uvx --from git+https://github.com/8b-is/ultra-ralph-local ultra-ralph-local
Or point it at another workspace:
uvx --from git+https://github.com/8b-is/ultra-ralph-local ultra-ralph-local \
--workspace /path/to/workspace
Loop mode
Run continuously every 33 minutes:
uvx --from git+https://github.com/8b-is/ultra-ralph-local ultra-ralph-local loop
Custom interval:
uvx --from git+https://github.com/8b-is/ultra-ralph-local ultra-ralph-local loop --interval 900
CTRL-C requests a graceful stop: the current run finishes, then the loop exits.
Loop output is also appended to ralph-loop.log inside the workspace.
Configuration precedence
Highest to lowest:
- CLI flags
- environment variables
- saved config file
- built-in defaults
Supported environment variables:
OPENROUTER_API_KEYHF_TOKENRALPH_DIRorULTRA_RALPH_WORKSPACERALPH_HF_REPORALPH_HF_PATHRALPH_UPLOAD
Upload behavior
Uploads are disabled until explicitly enabled in setup, saved config, RALPH_UPLOAD=true,
or --upload. A Hugging Face token alone does not enable uploads. Existing explicit
upload preferences remain in effect. Config files without an upload preference default
to disabled.
Uploads are non-fatal.
If Hugging Face auth is missing or upload fails:
- the local run still succeeds
decisions.logis still updated- the CLI prints a warning
Disable uploads for one run:
uvx --from git+https://github.com/8b-is/ultra-ralph-local ultra-ralph-local --no-upload
Override the default destination:
uvx --from git+https://github.com/8b-is/ultra-ralph-local ultra-ralph-local \
--hf-repo your-name/your-dataset \
--hf-path ralph/decisions.log
Decision log verification
New records use digest|timestamp|decision on one line. The SHA-256 input is
previous_digest + "\n" + decision + "\n" + timestamp, encoded as UTF-8,
using exactly the stored timestamp and decision. The first previous digest is
empty. Decision line breaks are replaced with spaces and outer whitespace is
trimmed before hashing and writing.
Older records hashed an unrecorded higher-precision timestamp and sometimes untrimmed text, so they cannot generally be independently verified. Existing records are preserved; new records link to the last stored digest. This does not retroactively verify the legacy prefix. A hash chain alone does not authenticate its author or prevent someone from rewriting the whole file.
Workspace inputs
The current workspace is the prompt context.
Optional files/directories:
workspace.txt: extra plain-text contextdyad-mapping/: additional context from a local checkout ofpeterlodri-sec/dyad-mapping, usingREADME.md,essences.md, and the latestsession-*-summary.md
If those files are absent, the tool still runs.
Local development
Clone the repo, then run:
uv run ultra-ralph-local setup
uv run ultra-ralph-local
uv run ultra-ralph-local loop
Run tests:
uv run --with pytest pytest
Repo files
src/ultra_ralph_local/cli.py: main CLIstart_ralph_loop.sh: thin local wrapper arounduv rundyad-mapping/: optional context files mirrored frompeterlodri-sec/dyad-mapping
Security notes
- no API keys are committed
- config is written to a user config file, not the repo
- uploads use the Hugging Face API, not an external
hfCLI dependency decisions.logandralph-loop.logare local runtime artifacts and are ignored
Main constellation
The constellation — a sovereign mesh of art, music, books, math, and machine intelligence.
Eleven surfaces, one commons. Self-hosted, self-owned, rendered in the open.
Footer links mirrored from vaked.dev:
License
MIT. See LICENSE.