DEV Community: Fernando Paladini

Run Local Audio Transcription with EchoTranscribe and Whisper

Fernando Paladini — Mon, 03 Aug 2026 12:35:57 +0000

Sending a recording to a hosted transcription service is convenient, but it also creates a data-handling decision. Meeting audio, interviews, research notes, and draft content may be easier to process when the files stay on the computer that owns them.

This tutorial walks through the documented development path for EchoTranscribe, an MIT-licensed desktop application by Fernando Paladini. It combines a Tauri desktop shell, a React and TypeScript frontend, and a local FastAPI backend that loads Whisper models through faster-whisper.

The goal is not to claim that local transcription is automatically more accurate or faster. The useful outcome is a reproducible local workflow: start the backend, open the desktop app, choose a model, transcribe supported audio, inspect timestamps, and export TXT, SRT, or JSON.

TL;DR

Use the stable v0.1.1 release, install the frontend dependencies, start the backend, and then run the Tauri development app in a second terminal.

git clone --branch v0.1.1 https://github.com/paladini/echo-transcribe.git
cd echo-transcribe
npm install

In the first terminal, start the Python backend:

cd src-tauri/backend
python main.py

In the second terminal, from the repository root, start Tauri:

npm run tauri dev

The backend documents its API at http://localhost:8000/docs, and the Tauri window should open the frontend automatically.

Prerequisites

The v0.1.1 README lists these prerequisites:

Node.js 18 or newer
Python 3.8 or newer
Rust for Tauri compilation
Microsoft Visual Studio C++ Build Tools on Windows
The Linux system packages documented in the README when developing on Ubuntu or Debian

The project also has macOS setup guidance using Homebrew. Tauri compilation adds platform-specific requirements, so a successful Python installation alone is not enough to build the desktop application.

The backend requirements pin FastAPI 0.104.1, Uvicorn 0.24.0, faster-whisper 0.9.0, Pydantic 2.5.0, and supporting packages. PyTorch and torchaudio are specified as version 2.0.0 or newer. Read the repository's current dependency files before installing if you are working from main instead of the stable tag.

Start the local backend

The README provides a startup script for each platform, but the manual path makes the process easier to inspect. From the repository root, run:

cd src-tauri/backend
python main.py

The backend creates model and temporary directories below ~/.echo-transcribe. It searches ports 8000 through 8004 and writes the selected port to backend_port.txt. When port 8000 is available, the documented API address is http://127.0.0.1:8000.

Before launching the desktop shell, check the backend's health endpoint:

curl http://localhost:8000/health

A healthy response includes status set to healthy. You can also open the generated OpenAPI documentation at http://localhost:8000/docs to inspect the available routes.

The first transcription may take longer because the selected Whisper model is downloaded when it is not already present. The source stores models under the .echo-transcribe/models directory in your home folder.

Launch the Tauri desktop app

Keep the backend terminal running. Open another terminal at the repository root and run the exact command documented for Tauri development:

npm run tauri dev

The Tauri configuration uses http://localhost:1420 as the development URL and starts the Vite frontend with npm run dev. The desktop window is configured with a 1200 by 800 initial size and can be resized.

The application is not a remote client. Its frontend is paired with the backend running on your machine, and the backend's CORS configuration allows the local Vite origin and tauri://localhost. That local arrangement is part of the privacy boundary, but it is not authentication.

Transcribe a file

In the app, select one audio file or a batch. The README documents MP3, WAV, FLAC, M4A, OGG, and WebM input, with a maximum of 10 files selected at once for batch transcription.

Choose one of the models exposed by the backend:

tiny: 39 MB, faster with lower expected accuracy
base: 74 MB, a balance between speed and precision
small: 244 MB, better quality with medium speed
medium: 769 MB, higher quality with slower processing

These sizes are the values in the tagged source's model metadata, not a benchmark for your machine. Runtime depends on the audio, model, dependency versions, and whether the environment can use an available accelerator.

Leave automatic language detection enabled for a first test, or choose a language manually. The backend first validates the extension and model name. It then writes the upload to a temporary file, loads the selected Whisper model, transcribes with word timestamps enabled, and schedules cleanup of the temporary file.

The result can be reviewed in the interface and exported as TXT, SRT, or JSON. Word-level timestamps are included in the backend response when the transcription model returns them.

Verify the path without transcribing a large recording

Use a short audio file that you are allowed to process. Verify the workflow in this order:

Confirm that /health returns a healthy status.
Open /models and inspect the four model entries.
Start with the tiny or base model to reduce the initial download and wait time.
Transcribe a short file in one of the documented formats.
Confirm that text and timestamps appear in the result.
Export one result as TXT, SRT, or JSON and open the exported file.

The backend also exposes POST /transcribe and POST /transcribe-batch. The interactive Swagger page at /docs is the safest place to inspect the current multipart field names instead of guessing at a curl command. The single-file route accepts an uploaded file, a model, an optional language, and the auto_detect_language flag.

Why the local architecture works

The project separates three responsibilities:

Tauri packages the desktop experience and connects the frontend to the local application.
React, TypeScript, and Vite provide the interface and development server.
FastAPI handles uploads, model loading, transcription, language detection, timestamps, and cleanup.

This separation keeps model execution out of the browser UI. It also makes the backend inspectable through OpenAPI while keeping the default network path on loopback. The model cache avoids downloading the same model for every request, and the temporary directory gives the backend a controlled place to write uploaded audio during processing.

Failure modes and security boundaries

The desktop window cannot load the backend. Check that the Python process is still running and that port 8000 is available. If the backend selected another port, inspect backend_port.txt and the terminal log.

The first request appears stuck. Model loading and download happen before transcription. Check the network connection and backend logs. Do not use a long recording as the first test.

The file is rejected. Confirm that its extension is one of MP3, WAV, FLAC, M4A, OGG, or WebM. The backend validates the suffix, not the contents of every possible container.

The build fails on a platform dependency. Install the platform prerequisites listed by the README, including Rust and the required Linux packages or Windows C++ Build Tools.

You want to expose the API to another machine. Stop and design that boundary first. The current backend allows broad methods and headers for its two local origins, and the repository does not document user authentication, quotas, or a production reverse proxy. Local execution limits where the default app sends data, but it does not turn an unauthenticated API into a safe public service.

You process someone else's recording. Local execution does not replace consent, retention, copyright, or organizational data-handling requirements. Only transcribe audio you are authorized to process.

FAQ

Does EchoTranscribe require a cloud API key?

The documented backend loads Whisper models locally through faster-whisper and downloads missing models to the local model directory. The tutorial does not require a hosted transcription key.

Can I use it without a GPU?

The repository documents model choices and local execution, but it does not promise a particular hardware configuration or processing speed. Start with tiny or base and check the backend logs on your machine.

Is `main` the same as the release?

No. This tutorial uses the stable v0.1.1 tag. The repository's default branch can change, so pin the tag when you need the commands and model list described here.

Is it ready to expose as a shared service?

That is outside the documented guarantee. Add authentication, request limits, storage controls, logging decisions, and a deliberate network boundary before considering shared access.

Takeaway

EchoTranscribe is a useful pattern for local AI desktop tooling: a Tauri shell, an inspectable FastAPI service, a persistent model directory, and explicit export formats. Pin v0.1.1, verify the health endpoint, test with a short authorized recording, and treat the lack of authentication as a real deployment boundary.

Which local transcription feature would you verify next: speaker separation, stronger export controls, or authenticated access for a small team?

AI assistance disclosure

AI assistance was used to organize this tutorial and review its wording. The release, commands, versions, routes, model names, file paths, limitations, and security notes were checked against the public v0.1.1 repository sources linked above. No performance benchmark or personal usage claim is implied.

Self-Host Audio Stem Separation with Docker and Demucs

Fernando Paladini — Sun, 02 Aug 2026 12:36:20 +0000

Turning a song into a vocal track, an instrumental, or separate drums and bass often leads to a choice between a hosted service and a complicated local machine setup. Hosted services can create privacy and upload concerns. A local setup can require Python, FFmpeg, PyTorch, model downloads, and a way to retrieve generated files.

This tutorial uses voice-separator-demucs, an MIT-licensed self-hosted application by Fernando Paladini. It provides a browser interface and a FastAPI backend for separating audio with Demucs. The Docker path keeps the model cache persistent and maps generated files to a directory on your computer.

The result is a local service at http://localhost:7860. You can upload an MP3, WAV, FLAC, M4A, or AAC file, choose stems such as vocals or drums, and download the generated MP3 files without sending the audio to a hosted application.

TL;DR

Clone the repository, start the Docker Compose service, open the local web interface, and upload an audio file. The current Compose file maps ./static/output to the container output directory and stores the model cache in a named Docker volume.

git clone https://github.com/paladini/voice-separator-demucs.git
cd voice-separator-demucs
docker compose up -d

Open http://localhost:7860. The first separation downloads the selected model, so the initial run takes longer than later runs.

Prerequisites

You need:

Docker with the Compose plugin
A machine with enough disk space for Python dependencies and the Demucs model cache
An audio file you are allowed to process

The repository also documents a Python path that needs Python 3.8 or newer and FFmpeg. Docker is the more reproducible starting point because the Dockerfile installs FFmpeg and uses Python 3.9 inside the image. The Dockerfile currently installs the unpinned dependencies from requirements.txt, so this is a current-branch setup rather than a fully lockfile-reproducible build.

Start the local service

Clone the repository and start the service:

git clone https://github.com/paladini/voice-separator-demucs.git
cd voice-separator-demucs
docker compose up -d

The Compose configuration exposes port 7860, mounts ./static/output at /app/static/output, and persists /root/.cache in a named volume called model-cache. The host output mount is useful because files created by the container remain available in the repository's static/output directory.

Check that the API is alive before uploading anything:

curl http://localhost:7860/health

The application defines this endpoint as a simple health check. A successful response has the following shape:

{"status":"healthy","message":"Voice Separator API is running"}

You can also open the interactive FastAPI documentation at http://localhost:7860/docs. The documented API includes /api/stems, /api/separate, and /api/separate-youtube.

Separate vocals with the API

The browser interface is the easiest path, but the API makes the workflow scriptable. The upload endpoint accepts a multipart file, a comma-separated stems value, and an optional model name. The default model is mdx_extra_q and the default stem is vocals.

The following command uses the repository's current endpoint and parameter names:

curl -X POST "http://localhost:7860/api/separate" \
  -F "file=@./example.mp3" \
  -F "stems=vocals"

On success, the response includes success: true, the processed stems, an estimated processing time, and a file URL such as /static/output/vocals_<id>.mp3. Because the output directory is mounted by Compose, the same file is also available under static/output on the host.

To request more than one stem, pass a comma-separated list:

curl -X POST "http://localhost:7860/api/separate" \
  -F "file=@./example.wav" \
  -F "stems=vocals,instrumental"

The available selections in the current implementation are drums, bass, other, vocals, and instrumental. The instrumental result combines drums, bass, and other. The backend validates both the model name and the selected stems before processing the file.

Understand the model choices

The interface exposes four model names: mdx_extra_q, mdx, htdemucs, and htdemucs_ft. The application selects CPU for mdx_extra_q and mdx when a GPU is unavailable. The two htdemucs variants require a CUDA-capable GPU in the current separator implementation.

For a first local test, keep the default mdx_extra_q model and request only vocals. The README describes it as the CPU-oriented default. It also notes that the first model download is about 200 MB, while exact disk usage and runtime depend on the dependency versions, hardware, audio length, and selected model.

Do not treat the README's rough processing times as a benchmark. They are operational guidance, not a guarantee. A longer file, several selected stems, or CPU-only processing can take substantially longer.

Why the Compose mounts matter

There are two different persistence concerns:

The named model-cache volume prevents the model cache from disappearing when the container is recreated.
The bind mount keeps generated audio in ./static/output on the host.

You can inspect the container and output files with:

docker ps --filter "name=voice-separator"
Get-ChildItem .\static\output

The second command is for PowerShell. On macOS or Linux, use ls -lah static/output instead. If you use the single docker run command from the README without a bind mount, output files stay inside the container and must be copied out with docker cp.

When you are done, stop the service without deleting the cache:

docker compose down

To remove the persistent model volume as well, use docker compose down -v. That forces a future startup to download the model again.

YouTube input and its boundary

The application also exposes /api/separate-youtube and uses yt-dlp to download audio before separation. The current route validates a YouTube URL and rejects videos longer than 10 minutes. It then removes the temporary downloaded audio after processing.

This feature does not remove copyright or platform obligations. Process only material you have permission to download and transform. A public URL is not automatically a license to copy its audio.

For a privacy-focused local workflow, prefer direct file upload. Both routes write output into the local application's static directory, and the app does not provide authentication in the current implementation. Do not expose port 7860 to the public internet without adding an access-control and deployment boundary appropriate for your environment.

Failure modes to check first

FFmpeg errors: The Docker image installs FFmpeg. If you use the Python path, install FFmpeg separately as described in the repository README and confirm that ffmpeg -version works.

Slow first request: Model loading and the initial model download happen before separation. Check the container logs with docker compose logs -f and wait for the model to finish loading.

Out of memory: Use a smaller input, select fewer stems, close competing workloads, or use the CPU-oriented default. GPU model choices are not a universal speed-up if the machine lacks the required GPU memory.

No files on the host: Confirm that you started with docker compose up -d from the repository directory and that static/output is the directory mounted by the Compose file. A plain docker run without -v keeps output inside the container.

Browser security warnings: The documented default is plain HTTP on localhost. The README includes an optional self-signed HTTPS example for local development. A self-signed certificate is not a production trust model, and the current application has no authentication layer.

Reproducible verification

After the health check, verify the core path in this order:

Open /api/stems and confirm the available stem names.
Upload a short audio file with stems=vocals.
Confirm the response contains success: true and a generated output URL.
Confirm a new MP3 appears in static/output.
Play the output and compare its duration with the input.

The repository includes unit tests for mono-to-stereo tensor normalization. You can run the lightweight test module in a Python environment with its available dependencies:

python -m unittest tests/test_audio_tensor_utils.py -v

The test suite does not prove that every model, codec, GPU, or long audio file works. It verifies a focused preprocessing behavior used by the separator.

FAQ

Does the audio leave my computer?

The Docker workflow runs the application locally. If you use the YouTube route, the app downloads the requested source first. Local execution does not make the application safe to expose publicly, because the current API has no authentication.

Can I run it without a GPU?

Yes, the current implementation selects CPU for mdx_extra_q and mdx. The htdemucs variants require a CUDA GPU according to the source code.

Is this a production-ready hosted service?

No claim like that is supported by the repository. Treat it as a local or controlled self-hosted application. Add authentication, resource limits, storage cleanup, and a deliberate reverse-proxy boundary before considering a shared deployment.

Takeaway

The useful pattern is not only the separation model. It is the local boundary around it: Docker packages the runtime, a named volume preserves expensive model downloads, and a host bind mount makes generated files easy to retrieve. Start with the default CPU-oriented model and a short file, verify the health and output paths, then decide whether your hardware and usage rights support larger jobs.

Have you found a reliable way to add authentication and per-job storage limits to a local audio-processing API without making the setup too complex?

AI assistance disclosure

AI assistance was used to organize this tutorial and review its wording. The commands, endpoint names, model names, file paths, limitations, and security notes were checked against the current public repository sources linked above. No performance benchmark or personal usage claim is implied.

Style Active Admin 3 and 4 with One Rails Theme Gem

Fernando Paladini — Fri, 31 Jul 2026 12:37:32 +0000

Active Admin gives Rails applications a productive admin surface, but its styling depends on which major version your application uses. Active Admin 3 expects a Sass and Sprockets workflow. Active Admin 4 uses Tailwind CSS v4 and a different source-to-build path. A theme that treats them as the same problem can leave you with a successful generator run and an unstyled page.

This tutorial uses activeadmin-claude-theme, an MIT-licensed Rails engine gem, to install the same warm visual language on both Active Admin branches. The current 0.2.0 release includes a version-aware generator, Active Admin 3 support, and Active Admin 4 support. The theme is a community project inspired by Claude aesthetics. It is not affiliated with or endorsed by Anthropic.

TL;DR

Add the gem, run its installer, and then use the asset step that belongs to your Active Admin version:

bundle add activeadmin-claude-theme
rails generate activeadmin_claude_theme:install

# Active Admin 4 only
npm run build:css

For Active Admin 4, the generator keeps Tailwind source in app/assets/tailwind/active_admin.css and builds the served file into app/assets/builds/active_admin.css. For Active Admin 3, it writes the Sass entry point at app/assets/stylesheets/active_admin.scss.

Prerequisites

You need an existing Rails application with Active Admin installed, Ruby 3.2 or newer, and Rails 7.2 or newer. The theme's release notes document support for Active Admin 3.2 through the 3.x line and Active Admin 4.0.0.beta22 or newer. Active Admin 4 also requires the Node-based Tailwind build used by its asset setup.

The commands below assume you have already run Active Admin's installer. If you are starting from an empty Rails application, follow the Active Admin installation guide first, then return here.

Install the theme

Add the gem to your application's Gemfile:

gem "activeadmin-claude-theme"

Install dependencies and run the generator:

bundle install
rails generate activeadmin_claude_theme:install

The generator detects the installed Active Admin major version. It does not ask you to choose a stylesheet manually, because the integration points are different.

Active Admin 4: build the Tailwind output

Active Admin 4 uses Tailwind v4. The theme generator vendors its CSS into the application, imports it from the Tailwind source, and updates the build script when the standard setup is present.

Run the CSS build after installation:

npm run build:css
bin/rails server

The important distinction is source versus served output:

app/assets/tailwind/active_admin.css   # Tailwind source
app/assets/builds/active_admin.css     # compiled output

The source file is outside the Propshaft-served path. Serving the uncompiled source instead of the build output is a common reason for seeing an admin page with little or none of the expected styling.

The generator also adds the theme gem's view directory to the Tailwind content configuration when tailwind-active_admin.config.js exists. That lets Tailwind see the engine templates that contain utility classes. The implementation uses bundle show activeadmin-claude-theme to locate the installed gem rather than asking you to hard-code a machine-specific path.

Active Admin's own dark-mode toggle remains part of the AA4 setup. The theme remaps color scales and adds semantic variables while preserving the existing hooks instead of replacing the whole plugin.

Active Admin 3: use the Sass entry point

Active Admin 3 follows a Sprockets and Sass path. After running the same generator, check app/assets/stylesheets/active_admin.scss:

@import "activeadmin_claude_theme/aa3/base";

Then make sure your application includes a Sass pipeline such as sassc-rails or dartsass-rails, and restart Rails:

bundle install
bin/rails server

The AA3 integration replaces the legacy active_admin/base import when it finds one. If the stylesheet has a different structure, the generator appends the theme import so you can review the result before committing it.

There is an intentional feature difference here: Active Admin 3 receives the light theme only. Native dark mode is documented for the AA4 path because Active Admin 3 does not provide the same dark-mode mechanism.

Customize the palette without replacing the theme

The theme exposes semantic tokens for the common colors. On Active Admin 4, override CSS variables after the theme import:

:root {
  --claude-primary: #d4845f;
  --claude-canvas: #fff8f0;
}

.dark {
  --claude-canvas: #121110;
}

On Active Admin 3, set Sass variables before importing the base theme:

$claude-primary: #d4845f;
$claude-canvas: #fff8f0;
@import "activeadmin_claude_theme/aa3/base";

This is safer than editing generated gem files. The repository's design token reference lists the available roles, including the accent, canvas, ink, and body colors.

Verify the installation

Use a short checklist rather than relying only on a successful generator exit code:

Confirm the gem is locked to the version you reviewed. For this tutorial, that is 0.2.0.
On AA4, confirm the Tailwind source exists under app/assets/tailwind/ and the compiled CSS exists under app/assets/builds/ after npm run build:css.
On AA3, confirm the Sass entry imports activeadmin_claude_theme/aa3/base.
Open an Active Admin dashboard and an index page. Check the header, navigation, table, form, and login screen.
On AA4, toggle dark mode and verify that the existing control still works.
Change one semantic token, rebuild the relevant assets, and confirm the rendered color changes.

For a repository-level verification, the project documents separate dummy applications and integration commands for AA4 and AA3. Running those tests is useful when upgrading the theme or changing its overrides:

# AA4
cd test/dummy
npm install
npm run build:css
ruby bin/rails db:setup db:seed
cd ../..
ruby -Itest test/activeadmin_claude_theme_test.rb
ruby -Itest test/integration/theme_integration_test.rb

# AA3
BUNDLE_GEMFILE=gemfiles/activeadmin_3.gemfile bundle install
cd test/dummy_aa3
bundle exec rails db:setup db:seed
cd ../..
DUMMY_PATH=dummy_aa3 BUNDLE_GEMFILE=gemfiles/activeadmin_3.gemfile \
  ruby -Itest test/activeadmin_claude_theme_test.rb

Why the version-aware generator matters

The visual goal is shared, but the integration boundary is not. AA4 needs Tailwind source discovery, a build command, and view content paths. AA3 needs a Sass import and a Sprockets-compatible manifest. The generator makes that branch explicit in code through Active Admin version detection.

It also handles a subtle AA4 failure mode: a legacy app/assets/stylesheets/active_admin.css file can be moved to app/assets/tailwind/active_admin.css before compilation. That keeps the source from being treated as the final served asset by Propshaft.

The result is not magic CSS. It is a small Rails engine with two integration paths, shared design tokens, and limited view overrides. That makes the generated changes inspectable in your own application.

Failure modes and security boundaries

If rails generate activeadmin_claude_theme:install reports an unsupported Active Admin version, check the resolved bundle. Active Admin 2.x is outside the documented support range. If AA4 looks unstyled, rebuild CSS and check the source and build locations before changing templates. If AA3 fails to compile, verify the Sass dependency and import path.

The theme changes presentation. It does not provide authentication, authorization, CSRF protection, or a security review of your admin resources. Active Admin's authorization and Devise configuration remain application responsibilities. Keep the admin surface behind your existing authentication and authorization controls, and review generated template changes before deploying them.

Also treat the name accurately: this is a community theme, not an Anthropic product. The visual inspiration is not a security or compatibility guarantee.

FAQ

Does one installation command support both Active Admin versions?

Yes. The generator detects Active Admin 3 or 4 and applies the corresponding asset setup. The follow-up verification differs because AA4 needs a CSS build while AA3 uses Sass.

Do I need Node.js for Active Admin 3?

Not for the theme's documented AA3 path. AA3 uses Sass through Sprockets. Node.js is required for the AA4 Tailwind workflow.

Can I use the theme with Propshaft?

Yes for the documented Active Admin 4 setup, provided Tailwind source stays under app/assets/tailwind/ and the compiled file is emitted under app/assets/builds/. AA3 typically uses Sprockets instead.

Can I keep my own brand colors?

Yes. Override the semantic CSS variables for AA4 or Sass variables for AA3, then verify the generated CSS in the browser. Use the design token reference to choose the right role instead of changing many selectors.

Takeaway

The useful lesson is not the palette. It is respecting the boundary between Active Admin 3's Sass pipeline and Active Admin 4's Tailwind pipeline. A version-aware installer can keep the setup small, but you still need to verify the actual source path, compiled asset, and rendered admin pages.

Have you kept one Rails admin theme working across a major asset-pipeline change? I would be interested in which compatibility boundary caused the most maintenance in your application.

AI assistance disclosure

AI assistance was used to organize this tutorial and review its wording. The technical details and commands were checked against the project's current README, generator implementation, gemspec, changelog, FAQ, override map, and the Active Admin documentation linked above.

Trace AI Coding Changes to Requirements with Python and SARIF

Fernando Paladini — Thu, 30 Jul 2026 13:23:28 +0000

AI-assisted code can look complete while quietly missing a requirement, an expected file, a required test, or an acceptance condition. A green-looking diff does not prove that the change answers the request that created it.

This tutorial builds a small evidence check with SpecTrace for AI Coding. You will describe requirements in JSON, map implementation files and test results to those requirements, then generate a Markdown report plus machine-readable JSON and SARIF output for CI review.

The useful boundary is deliberate: SpecTrace does not ask an LLM whether code is good. Its version 0.1.0 implementation uses the Python standard library to check whether the evidence map covers the requirements that reviewers defined.

What you will build

The example models a checkout audit trail. One requirement asks for allow and deny decisions to be recorded. The evidence map links that requirement to a recorder file, a passing test, and two acceptance criteria.

The flow is:

requirements JSON + change map JSON
                    |
                    v
              SpecTrace verifier
              /        |        \
             v         v         v
       Markdown     JSON      SARIF for CI

If any required link is missing, the verifier reports a finding and returns a nonzero status. That makes the check suitable for a pull request gate, provided the change map itself is produced and reviewed as part of your workflow.

Prerequisites

You need Python 3.10 or newer and a PowerShell, macOS, or Linux shell. The project is distributed under the MIT license and version 0.1.0 currently uses only Python's standard library at runtime.

Clone the repository and enter it:

git clone https://github.com/paladini/spectrace-ai-coding.git
cd spectrace-ai-coding

The commands below use the repository's current documented examples. They do not require an API key, model account, or network call after cloning.

1. Validate the evidence inputs

SpecTrace keeps the requirement definition separate from the change map. The bundled spec contains requirement IDs, expected file patterns, acceptance labels, and required test names. The change map supplies the files, test statuses, and acceptance evidence.

Run the input validation command:

$env:PYTHONPATH = "$PWD\src"
python -m spectrace_ai_coding validate `
  --spec examples\checkout-audit-spec.json `
  --change-map examples\checkout-audit-change-map.json

You should see a message stating that two requirements, three file links, and two test results were validated. This step checks the structure and cross-references before report generation. It does not claim that the underlying application is correct.

The important design detail is the shared requirement ID. A file or test only contributes evidence when its requirement_ids list includes the ID from the spec. An unknown ID is a cross-reference error rather than a silent mismatch.

2. Generate reviewer and CI artifacts

Now run verification and request all three output formats:

$env:PYTHONPATH = "$PWD\src"
python -m spectrace_ai_coding verify `
  --spec examples\checkout-audit-spec.json `
  --change-map examples\checkout-audit-change-map.json `
  --out build\spectrace-report.md `
  --json-out build\spectrace-report.json `
  --sarif-out build\spectrace.sarif.json

The Markdown report is for human review. It includes a summary, a trace matrix, and requirement details. The JSON report is convenient for scripts that need counts and finding objects. The SARIF document follows the SARIF 2.1.0 format, so a CI platform that understands SARIF can display findings alongside other analysis results.

For the bundled example, verification prints that two requirements passed and returns status 0. Inspect the generated Markdown before treating that result as useful review evidence:

Get-Content build\spectrace-report.md

The report should identify the checkout audit requirement, its linked files, its required tests, and its acceptance evidence. It is more useful than a bare pass count because reviewers can see what the change map actually claims.

3. See a failure instead of trusting a green result

The verifier distinguishes missing evidence from passing evidence. For example, if a required test is absent from the change map, the requirement receives a missing-required-test finding. If the test exists with a status other than passed, it receives a required-test-not-passed finding.

Other checks cover missing linked files, uncovered expected file patterns, missing acceptance evidence, and unknown requirement IDs. The implementation uses file-pattern matching for expected files, so a pattern such as src/checkout_audit/*.py must match at least one linked path.

This is the central lesson: a traceability tool can make an omission visible, but it cannot manufacture evidence. A change map that says a test passed is still an assertion that your workflow must produce and reviewers must trust.

Why the split between spec and change map matters

The requirement spec is the review request. It describes what must be true and what evidence should exist. The change map is the implementation record. It says which files changed, which tests were reported as passed, and why acceptance criteria are considered covered.

Keeping those documents separate gives you a stable question for code review: does this change map prove the requirements, or does it only describe the files that were edited?

SpecTrace builds a RequirementTrace for each requirement. It gathers matching files, tests, and acceptance entries, then applies findings for each missing or invalid piece. A requirement is marked passed only when that list of findings is empty. Global cross-reference errors are also included in the final result.

Failure modes to plan for

A valid JSON file can still describe weak evidence

Validation checks the data model and references. It does not inspect your application source, rerun a test named in the change map, or verify that a summary is truthful. Treat the map as review material, not as an attestation generated by the verifier.

A passing trace does not judge code quality

The project explicitly does not use an LLM to evaluate semantic correctness. It also cannot determine whether a real pull request is correct beyond the supplied evidence map. Pair it with normal tests, code review, and domain-specific checks.

Inputs may contain sensitive data

The repository's security policy warns that requirement documents, file paths, test logs, and AI coding evidence can be sensitive. Use synthetic examples in issues and tests. Do not place tokens, private source code, customer paths, or production logs into a public change map.

A failed verification is intentionally not a test failure

The command returns status 2 when requirements fail or global findings exist. That is distinct from an input validation error, which returns status 1. Your CI wrapper should preserve that distinction if it reports remediation hints.

Reproducible verification

Run the repository's tests after the example commands:

python -m unittest discover -s tests

The current repository test suite contains seven tests. The bundled command path also verifies two requirements, writes Markdown, JSON, and SARIF files, and passes with status 0 in the checked working tree.

For a practical CI integration, keep the spec and change map in the repository, run validate first, then run verify and upload build\spectrace.sarif.json using your platform's SARIF support. The exact upload action is platform-specific and is outside SpecTrace's scope.

FAQ

Does SpecTrace need an AI provider?

No. Version 0.1.0 uses Python's standard library and does not call model APIs.

Does it replace tests?

No. It checks that required tests are represented in the change map with a passed status. It does not run those tests itself.

Can it prove that an AI-generated change is correct?

No. It proves only that the supplied evidence map covers the declared requirements according to the implemented rules.

Why generate SARIF?

SARIF gives CI and code-scanning tools a common format for displaying findings. The Markdown and JSON files remain useful for local review and automation.

Takeaway

The smallest useful safeguard for AI-assisted development is often not another model call. It is a concrete link between a requirement, the files that address it, the tests that support it, and the acceptance evidence a reviewer can inspect.

SpecTrace makes that link deterministic and reviewable. Start with one high-value requirement, keep the evidence map honest, and expand the check only when your team can explain where each piece of evidence comes from.

Have you found a reliable way to generate and review change maps in your AI coding workflow, or do you still rely mainly on the diff and test output?

AI assistance disclosure: AI was used to help organize and edit this tutorial. The commands, repository details, implementation claims, and verification results were checked against the public SpecTrace repository and its bundled examples.

Build a Typed Training Data Client in TypeScript with intervals-icu

Fernando Paladini — Wed, 29 Jul 2026 15:36:16 +0000

If your training dashboard starts as one HTTP request and grows into athletes, activities, wellness, workouts, gear, and performance data, a hand-written fetch wrapper becomes expensive to maintain. Every new endpoint adds another URL, another response shape, and another place to get authentication or retry behavior wrong.

This tutorial shows a small, reproducible path with intervals-icu, an open-source TypeScript client for the Intervals.icu API. The goal is not to build a complete training application. It is to establish a typed client, choose the right authentication boundary, call one service, and understand what changes when you move from version 1 to version 2 of the library.

TL;DR

Install the stable npm package, create an IntervalsClient with an API key or OAuth access token, and use service accessors such as client.athletes or client.activities. Version 2 uses typed service methods, retries selected transient failures, and defaults requests to the authenticated athlete.

Prerequisites

You need:

Node.js 18 or newer.
npm.
An Intervals.icu account with an API key, or an OAuth access token for an application acting for other users.
A TypeScript project that can run ESM modules.

The published package is intervals-icu version 2.2.1, and its package metadata declares Node.js >=18.0.0. The repository is public and licensed under MIT. The examples below target that stable package version, not an unreleased default-branch change.

Install the stable client

Create a small project and pin the package version used in this tutorial:

mkdir intervals-demo
cd intervals-demo
npm init -y
npm install intervals-icu@2.2.1
npm install -D typescript tsx

The package publishes both ESM and CommonJS entry points and exposes TypeScript declarations from its package root. Add a script so a .ts file can run without a separate build step:

{
  "type": "module",
  "scripts": {
    "start": "tsx src/index.ts"
  }
}

Create the smallest useful client

Create src/index.ts. Keep the credential outside source control. The placeholder below is intentionally not a real key:

import { IntervalsClient } from 'intervals-icu';

const apiKey = process.env.INTERVALS_API_KEY;

if (!apiKey) {
  throw new Error('Set INTERVALS_API_KEY before running this example');
}

const client = new IntervalsClient({
  apiKey,
  athleteId: '0',
  timeout: 30_000,
  maxRetries: 3,
  retryDelayMs: 1_000,
});

const athlete = await client.athletes.getAthlete();

console.log({
  id: athlete.id,
  name: athlete.name,
  ftp: athlete.ftp,
});

Run it with an environment variable rather than placing the key in the file:

INTERVALS_API_KEY=your-key npm start

On Windows PowerShell, use the equivalent session-scoped variable:

$env:INTERVALS_API_KEY = "your-key"
npm start

The expected result is an object containing the authenticated athlete's fields returned by the API. The exact values depend on the account, so a reproducible verification is to confirm that id is present and that the command exits successfully without printing the credential.

Why service accessors matter

The client groups operations by resource instead of putting every method on one large facade. The same client can read activities, events, wellness records, and workouts through separate accessors:

const recentActivities = await client.activities.listActivities({
  oldest: '2026-01-01',
  newest: '2026-01-31',
});

const events = await client.events.listEvents({
  oldest: '2026-01-01',
  newest: '2026-01-31',
});

const wellness = await client.wellness.listWellness({
  oldest: '2026-01-01',
  newest: '2026-01-31',
});

console.log({
  activities: recentActivities.length,
  events: events.length,
  wellnessRecords: wellness.length,
});

This layout is more than naming preference. It gives each resource group a discoverable boundary and lets the compiler catch common mistakes such as calling a method that belonged to the old facade API. The repository exports more than 100 typed methods across 16 service groups, including routes, gear, weather, custom items, fitness, performance, and search.

Add a typed activity query

Activity IDs are strings in version 2. Use the service accessor and an ID such as i55610271:

const activity = await client.activities.getActivity('i55610271');

console.log({
  id: activity.id,
  name: activity.name,
  type: activity.type,
  startDateLocal: activity.start_date_local,
});

Do not copy the old numeric-ID form from a version 1 example. The project's migration guide documents the breaking change and the replacement method names. That guide is worth reading before upgrading because all top-level facade methods were removed in version 2.

API keys, OAuth, and retry behavior

Use an API key for a personal integration. Use accessToken when your application obtains an OAuth bearer token for users:

const client = new IntervalsClient({
  accessToken: process.env.INTERVALS_ACCESS_TOKEN,
  athleteId: 'i12345',
});

The two credential options represent different trust boundaries. An API key is a personal secret and should stay on a server or local process you control. An OAuth access token is still a secret, even though it represents delegated access. Do not ship either value in browser JavaScript, commit it to Git, or include it in logs.

Version 2.2.0 added support for the server's Retry-After response and jittered exponential backoff. The client retries 429 and 5xx responses by default, and maxRetries and retryDelayMs let you tune that policy. Retries reduce sensitivity to temporary failures, but they do not make a request safe to repeat in every business workflow. Be especially careful with mutating methods and design your own application-level idempotency where the API operation requires it.

Common failure modes

The client constructs but the request fails

Constructing IntervalsClient does not prove that the credential is valid. Verify the environment variable, token scope, athlete ID, and the account's access to the requested resource. A request is the meaningful smoke test.

A version 1 example no longer compiles

Replace client.getAthlete() with client.athletes.getAthlete(), client.getEvents() with client.events.listEvents(), and numeric activity IDs with strings. These are intentional version 2 changes, not TypeScript configuration problems.

A request keeps retrying

Inspect the final IntervalsAPIError, including its HTTP status and retry information. A rate limit response may tell you when to try again, while a persistent 4xx response generally needs a credential, input, or permission change. Setting maxRetries to 0 can make failure timing clearer during local debugging.

The data looks different from your expectation

Treat the API response as an external contract. Keep the package types, the Intervals.icu API documentation, and your own validation close to the integration. Types improve the calling code, but they cannot guarantee that a remote service will never change.

FAQ

Does this client require an API key?

Every authenticated API request needs either an API key or an OAuth access token. The configuration makes apiKey optional because OAuth is supported, not because the API is anonymous.

Can I use it for activities and wellness data?

Yes. Version 2 exposes separate accessors for activities, wellness, events, workouts, and other resource groups. Check the current API permissions before requesting or mutating data.

Does it run in the browser?

The package is a Node.js client with credentials and server-oriented HTTP behavior. Do not put a personal API key in a browser bundle. If you need a browser UI, put a controlled backend between the UI and Intervals.icu and expose only the operations your application needs.

Takeaway

intervals-icu gives a TypeScript application a clear starting point for Intervals.icu integration: install a stable version, keep credentials server-side, use resource-specific services, and let the typed client handle the repetitive HTTP layer. Start with one read-only request, verify the returned shape, and add writes only after you understand the account permissions and retry consequences.

Have you found a better boundary for exposing training data to a frontend: a narrow backend API per feature, or a more general proxy with stricter authorization rules?

AI assistance disclosure: AI assistance was used to organize and edit this tutorial. The project documentation, package metadata, migration guide, changelog, and example API shape were checked against current primary sources before publication.

Give Your AI Assistant a Local Profile with mcp-me

Fernando Paladini — Wed, 29 Jul 2026 13:12:06 +0000

Every new AI coding session starts with the same small interview: What languages do you use? Which projects do you maintain? What kind of writing do you prefer? Repeating that context is tedious, and putting a complete personal profile into every prompt is difficult to maintain.

mcp-me takes a different approach. It stores a structured profile as local YAML files and exposes that profile through the Model Context Protocol. An MCP-compatible assistant can then read resources such as me://skills, me://projects, and me://career when the request benefits from personal context.

This tutorial shows a small, reproducible setup. You will install the released mcp-me package, initialize a profile, validate it, configure an MCP server, and add an instruction file that tells an agent when to consult the profile.

TL;DR

Install mcp-me with Node.js 20 or later, run mcp-me init, validate the generated YAML, and register this MCP server with your assistant:

{
  "mcpServers": {
    "me": {
      "command": "npx",
      "args": ["-y", "mcp-me", "serve"]
    }
  }
}

Then add an AGENTS.md file that tells your agent to call ask_about_me before answering requests where your background matters.

Prerequisites

You need:

Node.js 20 or later
An MCP-compatible assistant, such as Claude Desktop, Cursor, Windsurf, or VS Code with GitHub Copilot
A writable local directory for your profile

The package declares Node.js >=20.0.0 and uses the MIT license in its current package metadata. The commands below use the current npm release, mcp-me@0.6.0, which matches the repository's current main package metadata.

Check your Node.js version first:

node -v

Install and initialize the profile

For a globally available CLI, install the package with npm:

npm install -g mcp-me@0.6.0

The project also supports npx when you want to try it without a global install:

npx mcp-me@0.6.0 --help

Create the default profile directory and its templates:

mcp-me init

By default, the profile lives in ~/.mcp-me. The command creates .mcp-me.yaml plus YAML files for identity, career, skills, interests, personality, goals, projects, and frequently asked questions. You can initialize another directory by passing it as the command argument:

mcp-me init ./my-profile

Open the generated .mcp-me.yaml and uncomment only the sources you want to use. A minimal configuration can look like this:

generators:
  github: your-username
  devto: your-username

plugins:
  github:
    enabled: true
    username: your-username

The generator section describes data to collect when you run generate. The plugin section describes live integrations used while the MCP server is running. Keeping these concepts separate helps you decide whether a value should be a local snapshot or a live lookup.

Generate and validate local data

With the configuration in place, generate your profile:

mcp-me generate

The README documents public sources such as GitHub and DEV.to, along with many optional generators. Most generators do not need API keys, but the source-specific requirements still apply. For integrations that require credentials, read the generated comments and the project documentation before enabling them.

Validate the profile before connecting an assistant:

mcp-me validate

The command checks the profile YAML files against the project's schemas. A successful run ends with All profile files are valid!. Validation catches malformed YAML and schema problems before an assistant receives incomplete or unexpected context.

If you prefer not to install the CLI globally, use the same commands through npx and pass the profile directory explicitly:

npx -y mcp-me@0.6.0 validate ./my-profile

Connect the MCP server

The server defaults to ~/.mcp-me, so the simplest MCP configuration does not need a profile path. Add the following entry to the configuration used by your client:

{
  "mcpServers": {
    "me": {
      "command": "npx",
      "args": ["-y", "mcp-me", "serve"]
    }
  }
}

For a manually installed CLI, you can use mcp-me as the command instead of npx. If the profile is stored elsewhere, set MCP_ME_PROFILE_DIR in the client environment or pass the directory to mcp-me serve.

The project documents client-specific differences. For example, VS Code uses a servers key in its MCP configuration, while the configuration above uses mcpServers. Check the configuration guidance in the repository before copying the entry into a particular client.

Teach the agent when to use your profile

Connecting the server makes the resources available, but an agent still needs a reason to consult them. Add an AGENTS.md file to the project where you want this behavior:

# Agent Instructions

You have access to an MCP server called `me` that exposes my personal profile.

Always use `ask_about_me` or read the MCP resources below before answering any
request that could benefit from knowing who I am, including writing, code review,
documentation, career questions, and open-source contributions.

The repository includes a longer template at templates/AGENTS.md. You can copy it after a global npm installation:

cp "$(npm root -g)/mcp-me/templates/AGENTS.md" ./AGENTS.md

This file is guidance for the agent, not a security boundary. A model may still choose the wrong tool or misunderstand a request. Keep the instructions narrow, review them like any other project configuration, and avoid putting secrets into profile files.

Verify the result

Restart or reload your MCP client after changing its configuration. Then ask a question that requires profile context, such as:

Draft a short README section that reflects my TypeScript projects and open-source work.

The expected result is not a specific sentence. The useful verification is that the assistant can consult the me server and produce an answer grounded in the profile instead of asking you to restate the same background.

You can also verify the local server directly:

mcp-me serve

The server is intended to run as an MCP process, so a terminal may appear idle while it waits for protocol messages. Stop it with Ctrl+C after confirming that the process starts without a profile or configuration error.

Why this works

The profile is organized into stable resources rather than one large prompt. Identity, skills, career, projects, and other categories can be read independently. That gives an assistant a smaller, more targeted context surface for each request.

The same separation also makes updates local and reviewable. You can edit skills.yaml without rewriting an instruction file, regenerate public-source data when needed, and keep project-specific rules next to the project that owns them. The MCP server then provides a consistent interface for compatible clients.

Failure modes and limitations

If mcp-me is not found, confirm that Node.js 20 or later is installed and that the global npm binary directory is on your PATH. If you use npx, include -y in non-interactive setup scripts.

If validation fails, read the file and line reported by mcp-me validate. Do not assume that valid YAML is valid profile data. The schemas define the accepted structure.

If generation fails for one source, disable that source and test the remaining configuration. Some services require tokens or have rate limits. The README says that most generators use public APIs without keys, not that every source is unauthenticated.

The local-first design reduces unnecessary cloud transfer, but it does not make the profile harmless. Your local files can contain personal and career information, and an MCP client can expose that information to the model you connect. Use filesystem permissions, keep secrets out of YAML, and understand the data handling policy of your assistant before enabling the server.

The project is also not a memory system that guarantees perfect recall. It provides structured context and tools. The assistant still decides when to use them, and the profile is only as accurate as its files and generators.

FAQ

Does mcp-me store my profile in the cloud?

The project documents the profile as local YAML data and says the MCP server reads from disk. Your assistant still receives whatever profile content it requests, so local storage does not eliminate model-provider data handling.

Can I use a custom profile directory?

Yes. Pass a directory to init, validate, or serve, or set MCP_ME_PROFILE_DIR for the default profile path used by the server.

Do I need an API key for GitHub or DEV.to?

The documented generators use public APIs for many sources and do not require keys in the common case. Optional live plugins can have different authentication requirements.

Can I use mcp-me with more than one assistant?

Yes. Configure the same local MCP server in each compatible client. Review each client's configuration format and data-sharing behavior separately.

Takeaway

mcp-me turns repeated personal context into a local, structured MCP profile. Start with a few accurate YAML files, validate them, connect the server, and add agent instructions only after you understand what data should be available.

This tutorial was prepared with AI assistance. The repository documentation, package metadata, live package metadata, and the commands shown here were checked during preparation; the prose was reviewed for accuracy and limitations.

What personal context would save you the most repetition in an AI coding workflow: skills, project history, career details, or something else?

Translate Git Commit Messages Offline Without Rewriting Code

Fernando Paladini — Tue, 28 Jul 2026 19:45:07 +0000

A repository can have clean code and still have a difficult history. One commit says fix: corrige timeout, another says feat: add retry logic, and the next was generated by an AI coding assistant in a third language.

That inconsistency makes git log, release-note preparation, blame investigation, and onboarding harder than they need to be. Manually editing hundreds of messages is not realistic, while sending an entire private history to an external translation API may violate your team's privacy expectations.

This tutorial shows how to use git-translate-commits, an open-source Python CLI, to preview and normalize Git commit messages with a local translation engine. We will test the operation in a disposable clone first because changing a commit message necessarily changes its commit hash.

TL;DR

Install the CLI, create a disposable clone, and start with:

git-translate-commits --lang en --dry-run

The default engine uses Argos Translate. It downloads the required language model on first use and can then translate locally without an API key. Do not remove --dry-run until you have inspected the proposed messages and coordinated any history rewrite with everyone using the repository.

Why multilingual Git history becomes a maintenance problem

Mixed-language commits are not inherently wrong. The problem appears when a team expects one searchable language but people, automation, and coding agents produce several.

Consider a production incident. You search for "payment timeout", but the relevant fix was committed as corrige tempo limite do pagamento. Git cannot retrieve the concept if the words do not match. The same inconsistency affects changelog generation and tools that classify Conventional Commits.

The safest time to establish a commit-language policy is before merging. Existing repositories, however, may already contain years of mixed messages. A controlled history rewrite can normalize that history, provided the team understands the consequences.

Prerequisites

The current package metadata requires Python 3.10 or newer. You also need Git and either pipx, uv, or pip.

Install the command in an isolated environment:

pipx install git-translate-commits

# Alternative with uv
uv tool install git-translate-commits

The published PyPI package is currently version 1.0.1. During verification for this tutorial, the installed command responded to --version, although it printed v1.0.0. Treat PyPI metadata as the package-release version until that CLI display mismatch is corrected.

Step 1: Work in a disposable clone

Do not test a history-rewriting tool in your only local copy. Clone the repository into a separate directory and keep the original remote unchanged:

git clone https://github.com/your-org/your-repository.git history-translation-test
cd history-translation-test
git status

Replace the placeholder URL with a repository you are authorized to modify. Confirm that the working tree is clean before continuing.

For a shared repository, announce the experiment before anybody bases new work on rewritten commits. Even a correct rewrite creates new commit identifiers.

Step 2: Preview the translation

The required option is --lang. Use a language code such as en, es, or pt-BR.

Run the default local engine in dry-run mode:

git-translate-commits --lang en --dry-run

This is the critical safety step. --dry-run shows what would change without modifying the repository.

Review the preview for:

technical terms that should remain unchanged;
issue identifiers such as #123;
Conventional Commit prefixes such as feat: and fix:;
names, product terminology, and acronyms;
messages already written in the target language.

By default, the CLI is documented to skip messages already detected in the target language and preserve Conventional Commit prefixes.

Step 3: Reduce the scope when necessary

You rarely need to translate everything on the first attempt. Filters make a smaller experiment easier to review.

For example, preview commits from a date forward:

git-translate-commits \
  --lang en \
  --since "2026-01-01" \
  --dry-run

You can also select an author:

git-translate-commits \
  --lang en \
  --author "developer@example.com" \
  --dry-run

Other documented filters include --until, --branch, and --all-branches. Start with the current branch unless you have a reviewed migration plan for the entire repository.

Step 4: Understand what the tool preserves

git-translate-commits changes commit messages rather than source files. Its documented preservation rules include:

file contents;
author and committer names;
email addresses and timestamps;
Conventional Commit prefixes;
issue references;
Git trailers such as Co-authored-by and Signed-off-by.

Preserving those fields does not preserve commit hashes. A commit hash incorporates the commit message, so changing the message produces a different hash. Every descendant commit is rewritten as well.

The CLI creates a backup branch by default and writes .git-translate-log.json with the old-to-new mapping. Keep both until the rewritten history has been reviewed.

Step 5: Apply the rewrite only after review

Once the dry run is correct and the team has agreed on the migration window, run the same command without --dry-run:

git-translate-commits --lang en

The command asks for confirmation unless --force is used. Avoid --force during an initial migration because the prompt is a useful final pause.

After the command completes, inspect the result locally:

git log --oneline --decorate -n 20
git branch --list
git status

Compare representative messages with the preview, confirm that the backup branch exists, and inspect .git-translate-log.json.

Do not force-push immediately. Run your tests and compare the rewritten tree with the original branch first. The file trees should remain equivalent even though commit hashes differ.

Optional: use an LLM translation engine

The default local engine is the privacy-oriented path. The project also offers an optional llm extra through LiteLLM:

pipx install "git-translate-commits[llm]"
git-translate-commits --lang en --engine llm

This mode can use OpenAI, Anthropic, or an OpenAI-compatible provider. It changes the privacy, cost, and credential boundaries of the workflow. Prefer environment variables over command-line API keys, and confirm whether commit messages are allowed to leave your environment.

An OpenAI-compatible local server can provide a different local path, but model behavior and compatibility depend on that server. Validate it separately rather than assuming it behaves like the default Argos engine.

How to verify that only history metadata changed

Before rewriting, record the tree hash of the branch tip:

git rev-parse HEAD^{tree}

Run the same command after translation. If the tree hash is identical, the checked-in file snapshot at the branch tip is unchanged. This does not replace tests, but it is a useful deterministic check that the final source tree stayed the same.

Also verify:

the expected number of commits still exists;
author identities and timestamps are preserved;
issue references and trailers remain intact;
application tests pass;
the backup branch resolves to the original history;
collaborators know that their existing branches need reconciliation.

Limitations and safer alternatives

History rewriting is disruptive. Open pull requests, signed commits, release tags, CI references, and external links to commits can be affected. A backup branch helps recovery, but it does not remove the coordination cost.

For an active public repository, keeping existing history and enforcing one language only for future commits may be the better choice. A commit-message hook, contribution guideline, or pull-request squash policy can prevent new drift without invalidating old hashes.

Local neural translation also has quality limits. Domain-specific messages may need manual review. The optional LLM engine may improve context in some cases, but it introduces a provider and a data-transfer boundary.

Frequently asked questions

Does this translate source code?

No. The tool targets Git commit messages. You should still compare tree hashes and run tests before sharing rewritten history.

Can I preview without changing anything?

Yes. Use --dry-run, and keep it enabled while tuning language, branch, author, and date filters.

Will commit hashes change?

Yes. The message is part of the commit object, so changing it creates a new hash.

Does the default engine need an API key?

No. The default Argos Translate engine downloads language data on first use and operates locally afterward.

Should I rewrite a shared default branch?

Only with explicit team coordination and a recovery plan. For many active repositories, a future-only commit-language policy is safer.

Takeaway

A consistent Git history is useful, but consistency is not worth a surprise rewrite. Start in a disposable clone, use the offline dry run, narrow the scope, verify tree hashes, and involve the team before changing a shared branch.

git-translate-commits turns a repetitive editing problem into a reviewable workflow. The most important feature is not automatic translation. It is the ability to inspect the plan before accepting a destructive change.

Disclosure: This article was researched, fact-checked, and drafted with AI assistance using the current primary project sources linked above.

Would you rewrite an existing multilingual history, or enforce one commit language only from today forward?

Sync AI Agent Rules Across Repositories with GitHub Actions

Fernando Paladini — Tue, 28 Jul 2026 19:11:04 +0000

Your team improves an AGENTS.md instruction in one repository. A week later, another service still has the old rule. Cursor configuration has drifted too, and the shared Claude prompt was copied into only three of six projects.

This is an ordinary configuration-management problem hiding inside an AI tooling workflow. Copying files by hand does not scale, but pushing changes directly to protected default branches is not a good answer either.

In this tutorial, we will use team-ai-sync to keep AI agent instructions, prompts, and editor rules consistent across repositories. The workflow starts in dry-run mode, then distributes changes through normal pull requests so every update remains visible and reviewable.

What we are building

We will use one repository as the source of truth for shared AI guidance. A GitHub Actions workflow in that repository will:

Read a versioned synchronization manifest.
Compare the selected files with their destinations.
Preview changes without writing anything.
Create or update a pull request in each target repository after dry-run verification.

This approach is useful for files such as:

AGENTS.md and CLAUDE.md
GitHub Copilot instruction files
Cursor and Windsurf rules
reusable prompts
team-specific documentation for coding agents

The tool synchronizes files, not hidden model context. It does not decide whether AI authored anything, and it should never be used to distribute secrets.

Prerequisites

You need:

a GitHub repository that will hold the canonical files;
one or more target repositories;
permission to create branches and pull requests in those targets;
a fine-grained personal access token or GitHub App token for cross-repository access.

The normal workflow GITHUB_TOKEN can read the source repository. Cross-repository writes require a separate token because the built-in token is scoped to the repository running the workflow.

For a fine-grained token, grant access only to the target repositories. The documented minimum is:

Contents: read and write
Pull requests: read and write
Metadata: read
Issues: read and write only when you want the workflow to apply labels

Store the token as a repository or organization Actions secret. In this example, the secret is named TEAM_SYNC_ADMIN_PAT.

Step 1: Create the canonical files

Suppose your source repository has this structure:

shared-ai-guidance/
├── AGENTS.md
├── prompts/
│   └── review.md
└── .github/
    └── sync-config.json
~~~

Keep these files in Git like any other engineering policy. Changes then have authors, reviews, commit history, and an obvious rollback path.

## Step 2: Define the synchronization manifest

Create `.github/sync-config.json`:

~~~json
{
  "version": 1,
  "defaults": {
    "branchName": "chore/sync-ai-guidance",
    "commitMessage": "chore: sync shared AI guidance",
    "prTitle": "chore: sync shared AI guidance",
    "deleteOrphans": false
  },
  "targets": [
    {
      "repo": "your-org/api-service",
      "files": [
        {
          "source": "AGENTS.md",
          "destination": "AGENTS.md"
        },
        {
          "source": "prompts/review.md",
          "destination": ".github/prompts/review.md"
        }
      ]
    },
    {
      "repo": "your-org/web-app",
      "files": [
        {
          "source": "AGENTS.md",
          "destination": "AGENTS.md"
        }
      ]
    }
  ]
}
~~~

Replace the placeholder repository names with repositories you control.

The explicit source and destination paths make the contract easy to audit. team-ai-sync also validates paths: absolute paths, traversal through `..`, and `.git` paths are rejected. `deleteOrphans` is disabled by default, which makes initial adoption safer because an incomplete manifest will not remove files from target repositories.

## Step 3: Add the GitHub Actions workflow

Create `.github/workflows/sync-ai-guidance.yml` in the source repository:

~~~yaml
name: Sync AI guidance

on:
  workflow_dispatch:
  push:
    branches:
      - main
    paths:
      - AGENTS.md
      - prompts/**
      - .github/sync-config.json

permissions:
  contents: read

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - name: Check out the source repository
        uses: actions/checkout@v4

      - name: Preview synchronization
        uses: paladini/team-ai-sync@v1
        with:
          github-token: ${{ secrets.TEAM_SYNC_ADMIN_PAT }}
          config-path: .github/sync-config.json
          dry-run: true
~~~

Pinning `paladini/team-ai-sync@v1` follows the stable major-version example from the project documentation. For stricter supply-chain control, you can pin an immutable commit SHA and update it deliberately.

The `paths` filter prevents unrelated source changes from starting the job. Keeping `workflow_dispatch` is helpful while introducing the workflow because you can test configuration changes manually.

## Step 4: Run the dry run first

Commit the files, open the Actions tab, and run **Sync AI guidance**.

With `dry-run: true`, team-ai-sync calculates the work but does not push branches or create pull requests. Inspect the job log and confirm:

- every intended target is listed;
- every source resolves to the expected destination;
- no unrelated file is included;
- authentication works for all targets.

This is the most important rollout step. It separates configuration validation from mutation.

The action also exposes outputs including `changed`, `synced-targets`, `failed-targets`, and `pr-urls`. They are useful if you later want a summary step or a notification, but the first run should stay simple.

## Step 5: Enable reviewable synchronization

After the dry run is correct, remove this line:

~~~yaml
dry-run: true
~~~

Run the workflow again. For each repository with changes, the action creates or updates its synchronization branch and pull request. It does not merge the PR, approve it, bypass branch protection, or modify repository settings.

Review the generated diff exactly as you would review any other cross-repository policy change. The project includes a [public end-to-end demo pull request](https://github.com/paladini/team-ai-sync-demo-api/pull/1), so you can inspect the resulting workflow before enabling it in your own organization.

## Verification checklist

Before expanding to more repositories, verify one target end to end:

1. The workflow completes successfully.
2. The pull request contains only the configured files.
3. The destination paths are correct.
4. Branch protection still requires the expected reviews and checks.
5. A second run updates the existing PR instead of creating noisy duplicates.
6. A run with no source changes produces no unnecessary target change.

For implementation details, use the project's current [getting-started guide](https://github.com/paladini/team-ai-sync/blob/main/docs/getting-started.md), [authentication guide](https://github.com/paladini/team-ai-sync/blob/main/docs/authentication.md), and [security model](https://github.com/paladini/team-ai-sync/blob/main/docs/security.md). The action is also listed on the [GitHub Marketplace](https://github.com/marketplace/actions/team-ai-sync).

## Security boundaries and limitations

Centralization increases consistency, but it also increases the importance of the source repository and its credentials.

- Protect changes to the canonical files with code owners and required review.
- Scope tokens to the smallest possible repository set and permissions.
- Prefer a GitHub App for long-lived organization-wide automation.
- Never place secrets, credentials, or private model context in synchronized files.
- Start with one target and dry-run mode before broad rollout.
- Keep destructive orphan deletion disabled until its behavior is explicitly required and tested.

team-ai-sync supports GitHub Actions, GitLab CI/CD components, and a Bitbucket Pipe, but a single synchronization package targets repositories on the same platform. This tutorial intentionally covers GitHub only.

## Frequently asked questions

### Does team-ai-sync write directly to the default branch?

No. It creates or updates a branch and pull request. Your existing review rules, checks, and branch protection remain the approval boundary.

### Can I synchronize different files to different repositories?

Yes. Each target declares its own file mappings, so a backend service can receive a different subset from a frontend project.

### What happens when a canonical file changes again?

The next workflow run compares the new source content with each destination and updates the synchronization pull request when needed.

### Is this limited to `AGENTS.md`?

No. It works with repository files in general. AI agent instructions, prompts, editor rules, and supporting documentation are common use cases.

## A practical next step

Start with one low-risk instruction file and one target repository. Run the workflow in dry-run mode, inspect the plan, and only then enable pull-request creation. Once that path is trustworthy, add repositories incrementally.

The goal is not merely to copy files faster. It is to make shared AI guidance behave like maintained engineering configuration: versioned, reviewable, reproducible, and difficult to forget.

> Disclosure: This article was researched, fact-checked, and drafted with AI assistance using the current primary project sources linked above.

How does your team currently prevent AI agent instructions from drifting across repositories?

Stop Letting AI Agents Guess Hashes, UUIDs, and JWTs

Fernando Paladini — Tue, 28 Jul 2026 18:38:11 +0000

AI coding agents are good at reasoning over messy requirements. They should not be improvising deterministic operations such as hashing a string, generating a UUID, decoding a JWT, formatting JSON, or calculating a CIDR range.

Yet that is exactly what happens in many AI-assisted workflows. The model writes a throwaway script, reaches for a random website, produces an answer from memory, or spends several tool calls on a task that already has a precise implementation.

I wanted those small operations to be boring again. So I built DevUtils MCP Server: an open-source MCP server that exposes 36 local developer utilities to MCP-compatible AI assistants.

TL;DR

DevUtils gives Cursor, Claude Desktop, Claude Code, VS Code, Windsurf, and other MCP clients a consistent set of tools for:

hashing and encoding;
UUID, Nano ID, password, and random-hex generation;
JWT inspection;
JSON formatting and querying;
timestamp, number-base, color, and byte conversion;
CIDR and IP operations;
common text transformations.

The operations run locally through an MCP stdio server and do not call external APIs. You can start it with:

npx -y devutils-mcp-server

Node.js 18 or newer is required.

The real problem is not Base64

Base64 encoding is easy. So is generating a UUID. That is why asking an AI model to handle these tasks feels harmless.

But a long agent workflow may need dozens of small, exact transformations. Each improvised implementation adds friction and another place for subtle mistakes:

a timestamp is interpreted in the wrong timezone;
a JWT expiration is displayed as an unreadable integer;
malformed JSON produces a vague error;
a CIDR calculation uses the wrong host range;
a model describes a hash instead of actually calculating it.

These are not reasoning problems. They are tool problems.

MCP lets us give the agent explicit operations with named inputs, validated schemas, and structured results. The model decides when to use a utility; the utility performs the deterministic work.

Install DevUtils in an MCP client

For Cursor or Claude Desktop, add this server to the client's MCP configuration:

{
  "mcpServers": {
    "devutils": {
      "command": "npx",
      "args": ["-y", "devutils-mcp-server"]
    }
  }
}

Claude Desktop stores this configuration in:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Cursor can use the same server definition in ~/.cursor/mcp.json.

VS Code uses a slightly different top-level key:

{
  "servers": {
    "devutils": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "devutils-mcp-server"]
    }
  }
}

Restart or reload the client after changing its configuration. The exact UI varies by client, but you should see tools with names such as generate_uuid, jwt_decode, json_validate, and cidr_calculate.

I also smoke-tested the currently published npm package directly: it completed the MCP initialization handshake, and tools/list returned all 36 tools.

Try four practical workflows

1. Generate identifiers without writing a script

Ask your assistant:

Generate three UUID v4 values and return them as a JSON array.

The agent can call generate_uuid with batch support instead of inventing identifiers or creating a temporary program. For shorter URL-friendly identifiers, it can use generate_nanoid with a configured length.

2. Inspect a JWT expiration date

Ask:

Decode this JWT and explain its issued-at and expiration timestamps in UTC.

DevUtils exposes jwt_decode for the header and payload and returns human-readable dates. It also provides jwt_validate for structure and expiration checks.

There is an important boundary here: decoding a token is not the same as cryptographically verifying its signature. Do not treat a decoded payload as trusted identity data unless your application verifies the signature and expected claims with the correct key and algorithm.

3. Turn broken JSON into a useful error

Ask:

Validate this JSON. If it is invalid, show me where the syntax fails. If it is valid, format it with two-space indentation.

The agent can combine json_validate and json_format. For simple extraction, json_path_query supports dot-notation paths, which is often enough to inspect an API response without bringing in a full query language.

4. Check a network range during debugging

Ask:

Calculate the network address, broadcast address, mask, host range, and host count for 10.42.0.0/20.

That maps directly to cidr_calculate. ip_validate can also classify IPv4 and IPv6 input before another network operation uses it.

These examples are intentionally ordinary. A utility server is valuable because it removes repeated micro-decisions from larger workflows.

What else is included?

The 36 tools are grouped into eight areas:

Hashing: MD5, SHA-1, SHA-256, SHA-512, bcrypt creation, and bcrypt verification.
Encoding: Base64, URL, HTML entity, and hexadecimal encoding and decoding.
Generators: UUID v4, Nano ID, password, and random hexadecimal values.
JWT: payload decoding plus structure and expiration validation.
JSON: formatting, validation, and path queries.
Converters: timestamps, numeric bases, colors, and byte units.
Network: CIDR calculation and IP validation.
Text: statistics, case conversion, slug generation, regex tests, diffs, and placeholder text.

The server is implemented in TypeScript with the MCP SDK, Zod schemas, and stdio transport. The repository is available under the MIT license, and the package is published on npm as devutils-mcp-server.

What “local” does and does not mean

DevUtils performs its utility operations in the local MCP process. It does not send a hash input or JSON document to a separate conversion API.

That does not automatically make every prompt secret-safe. Your AI client and model may still receive the text you provide before deciding to call the tool. Do not paste production tokens, passwords, customer data, or private keys into an AI conversation merely because the final utility runs locally.

The usual cryptographic rules also still apply. MD5 and SHA-1 remain available for compatibility and checksums, not for secure password storage. Use an appropriate password-hashing design when protecting credentials.

When should you not use it?

If you are writing application code, use the standard library or a focused dependency. A direct crypto or hashlib call is faster and easier to test inside the application than routing the operation through MCP.

DevUtils is aimed at AI-agent workflows: debugging, investigation, repository maintenance, data inspection, and other multi-step tasks where the assistant benefits from reliable utilities.

It is also not useful if your client does not support MCP, and it adds process and protocol overhead compared with a direct function call. The point is consistency and tool availability, not maximum throughput.

FAQ

Does DevUtils MCP Server require an API key?

No. The server's 36 utility operations do not require external API credentials. Installing the npm package initially requires access to the npm registry unless it is already cached.

Does it work only with one AI assistant?

No. It uses MCP over stdio, so it can work with clients that support that transport. The repository documents configurations for Cursor, Claude Desktop, Claude Code, VS Code, Windsurf, and Docker-based setups.

Can it verify that a JWT is authentic?

No. The JWT tools decode tokens and validate their structure and expiration. Authenticity requires cryptographic signature verification with the correct key, algorithm, issuer, audience, and application policy.

Are all operations performed without external utility APIs?

Yes. The transformations themselves run in the local server process. Your AI client's own data handling remains a separate concern.

Make deterministic work deterministic

AI agents should spend their reasoning budget on the parts of development that actually require reasoning.

If your assistant repeatedly writes one-off scripts for hashes, IDs, encodings, timestamps, JSON, or network calculations, try DevUtils MCP Server on GitHub. Test it on a real workflow, inspect the tool calls, and open a discussion if a small developer utility is still missing.

Host a Free Ghost Blog on GitHub Pages (Without Paying for a Server)

Fernando Paladini — Tue, 28 Jul 2026 14:42:31 +0000

Ghost is one of the nicest writing experiences in blogging. The catch? A normal Ghost install expects a server, a database, and usually a hosting bill.

GitHub Pages is free and reliable — but it only serves static files. It will not run Ghost for you.

So the real question is not “Can Ghost run on GitHub Pages?”

It is: Can I write in Ghost locally, then publish a static copy of my blog for free?

Yes. And after years of people hitting broken images, localhost links on the live site, and Python 2 install failures, that workflow finally got a proper refresh.

This post walks through the problem, the approach, and how to set it up with Ghost on GitHub Pages v3.0.0 — a major release that replaces the old brittle path with something you can actually maintain in 2026.

The problem in plain terms

You probably want some mix of these:

Ghost’s editor and admin UI
A public blog URL
$0/month hosting
No Kubernetes, no managed DB, no “just spin up a droplet”

GitHub Pages is perfect for the hosting part. Ghost is perfect for the writing part. They do not speak the same language out of the box.

The workable pattern has always been:

Run Ghost on your machine (localhost)
Generate a static HTML snapshot of the site
Push that snapshot to a GitHub Pages repo
Repeat whenever you publish a new post

That idea is solid. The tooling around it was the painful part.

What used to go wrong

If you tried this years ago (or inherited an old setup), you may remember:

Python 2 / buster dependency hell on modern machines
Live pages whose nav or tags pointed to http://localhost:2368
Broken images after publish
Scripts that published too much (or hung for confusing reasons)
Docs that assumed you already knew what a “static generator” was

Those were not niche complaints. They showed up repeatedly as real issues — and they are exactly what v3 targets.

What Ghost on GitHub Pages actually does

Ghost on GitHub Pages is a small open-source toolkit that wires that local-Ghost → static-site → GitHub Pages loop together for you.

At a high level:

Edit in Ghost (localhost:2373)
        ↓
gssg builds static HTML/CSS/assets
        ↓
Push to your GitHub repo
        ↓
Live blog on GitHub Pages

You keep writing in Ghost. Visitors get a fast static site. GitHub hosts it for free.

What’s new in v3.0.0

Version 3 is a real major update after a long stretch:

Before (Classic v2)	Now (v3)
Python 2 + buster	Node.js + wget only
Fragile link/image rewrite	Publishing via gssg
Manual / risky upgrades	`./migrate.sh` with automatic backup
Sparse docs	Plain-English guides in `docs/`

It also addresses long-standing bugs around localhost links, image paths, install errors, and publishing the wrong set of files. Details live in the changelog and v3 release notes.

Live demos:

Who this is for (and who it is not)

Good fit if you:

Want Ghost’s writing UX without paying for Ghost(Pro) or a VPS
Are fine editing locally and running a deploy script when ready
Prefer GitHub Pages (or can adapt the same static output elsewhere)
Use macOS, Linux, or Windows via WSL

Not a great fit if you need:

Live server-side Ghost features on the public site (members, dynamic search, server-rendered previews, etc.)
Instant publish from any device without touching your machine
A fully managed “click publish and forget” SaaS

Be honest with yourself here: this is static publishing with Ghost as the CMS, not “Ghost Cloud for free.”

Tutorial: set up a free Ghost blog on GitHub Pages

Prerequisites

Before installing:

Node.js LTS (v18 or v20) — nodejs.org
wget
A free GitHub account and a public repository for the blog
Internet access for the initial Ghost download

On macOS:

brew install wget
node --version

On Ubuntu/Debian:

sudo apt-get update
sudo apt-get install -y wget
node --version

Create an empty public GitHub repo (for example my-blog) and keep the clone URL handy.

Full checklist: Requirements.

Step 1 — Download v3

Grab the latest release:

github.com/paladini/ghost-on-github-pages/releases/latest

Extract it somewhere memorable.

Step 2 — Install

cd path/to/ghost-on-github-pages
chmod +x install.sh
./install.sh

This takes a few minutes. It installs Ghost locally. Your blog folder ends up at ~/.ghost.

When prompted, you can publish to GitHub immediately or skip and do it later.

Step 3 — Configure Ghost

Open:

http://localhost:2373/ghost

Create your admin account, write a test post, poke around the editor.

Local preview of the site:

http://localhost:2373

Step 4 — Publish to GitHub Pages

If you skipped deploy during install:

cd ~/.ghost
./deploy.sh

The script asks for:

GitHub username
Repository name
Repository URL

Wait ~10 minutes for Pages to catch up, then open:

https://YOUR_USERNAME.github.io/YOUR_REPO

Sanity checklist

[ ] Local blog loads at http://localhost:2373
[ ] ./deploy.sh finishes cleanly
[ ] The GitHub repo has new static files
[ ] The public URL loads
[ ] Post/tag links do not point at localhost

If something fails, start here: Troubleshooting.

Updating later

Edit at http://localhost:2373/ghost
Publish again:

cd ~/.ghost
./deploy.sh

That is the whole loop.

How publishing works under the hood

When you run deploy.sh, the flow is roughly:

Ensure Ghost is available locally
Use gssg to crawl/generate a static copy of the site
Rewrite URLs so the public site uses your GitHub Pages domain — not localhost
Push only the static output to your configured repo
GitHub Pages serves those files

v3 also includes helpers like scripts/validate-static.sh so you can catch broken links/images before visitors do, plus optional multi-site deploy profiles (deploy.sh --site / sites.conf) if you maintain more than one blog.

Saved deploy settings live in ~/.ghost/deploy.conf, so you are not retyping repo details every time.

Features worth knowing about

Beyond “install and deploy,” v3 ships with:

Simpler dependency story — no Python 2
More reliable static output — fewer broken images / localhost leaks
Migration path from Classic v2 — ./migrate.sh with automatic backup
Plain-English documentation — getting started, deploy, glossary, troubleshooting
Static validation script — catch bad links/images pre-publish
Multiple GitHub repos / site profiles — useful if you run more than one site
CI in the project itself — shellcheck + validation tests on the toolkit

If you are on Classic v2 and it still publishes fine, you can stay. Migrate when you hit Python errors, broken assets, localhost links, or you are setting up a new machine and do not want to resurrect Python 2.

Migration guide: docs/MIGRATION.md.

A note on expectations

This project will not magically turn GitHub Pages into a full Ghost server. Comments widgets, membership, newsletters, and other dynamic Ghost features need a real Ghost host or third-party services.

What it does well is the thing many indie writers and side-project blogs actually need:

A pleasant editor locally + a free, fast, public static blog.

If that is your goal, the v3 path is substantially less painful than the Classic era.

Quick links

Repo: paladini/ghost-on-github-pages
Latest release: v3.0.0 / latest
Getting started: docs/v3/GETTING-STARTED.md
Migration from Classic: docs/MIGRATION.md
v3 demo: paladini.github.io/ghost-on-github-pages-demo

Questions and bug reports welcome via GitHub Issues. Docs contributions count too — you do not need to be a developer to help.

If this saved you a hosting bill (or an afternoon fighting Python 2), a star on the repo helps other people find it.

Measure Your AI Coding Harness Maturity in CI with GitHub Actions

Fernando Paladini — Mon, 27 Jul 2026 11:57:05 +0000

Two teams can use the same model and the same prompt — and get completely different results.

The difference is often not the model. It is the harness: the guides, rules, skills, hooks, tests, and CI feedback wrapped around the agent.

Most repositories build that harness slowly. Almost none of them measure it. Worse: a pull request can quietly delete hooks.json or drop a CI gate, and nobody notices until an agent does something expensive.

This tutorial shows how to put a deterministic maturity score into your GitHub Actions pipeline with Harness Score — so AI-assisted repos get the same kind of ratchet you already expect from tests and lint.

What “AI harness maturity” means

Harness Score scans filesystem evidence across tools like Cursor, Claude Code, Windsurf, Cline, Continue, Codex, and Copilot. It returns:

a maturity level from L0 (Unharnessed) to L4 (Self-correcting)
a score across six dimensions (up to 108 points)
a ranked list of what to fix next

Level	Name	Rough meaning
L0	Unharnessed	Agents rediscover the project every session
L1	Documented	Substantive context file exists
L2	Guided	Scoped rules / skills + basic hygiene
L3	Sensing	Tests, lint, types, and CI feedback exist
L4	Self-correcting	Gate + feedback hooks close the loop

Important constraints (by design):

No LLM calls during the scan
No network during the scan
Same commit ⇒ same score

That is what makes the number safe to gate CI on.

Try it locally first:

npx harness-score@1.5.1

Why put this in GitHub Actions

Local scans are useful. CI is the contract.

With the Action in your pipeline you can:

Fail PRs that drop below a minimum maturity level
Show a job summary with the dimension breakdown
Post a sticky PR comment with score deltas vs the base branch
Emit a README badge that updates when maturity changes

Official Action: Harness Score on the GitHub Marketplace

Tutorial: add Harness Score to CI

1) Create the workflow

Add .github/workflows/harness.yml:

name: Harness maturity

on:
  pull_request:
  push:
    branches: [main]

jobs:
  harness:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: paladini/harness-score@v1
        with:
          min-level: '0'              # report only for now
          badge: 'harness-badge.svg'
          report: 'harness-report.md'

Commit, push, and open the Actions tab. You should see a job summary like:

Harness Score: L2 · Guided (65% maturity)

plus a per-dimension table.

Tip: for stronger supply-chain hygiene, pin the Action to a full commit SHA instead of @v1.

2) Start gating when you know your baseline

Once you know where the repo sits, raise the floor.

Example: require at least L3 · Sensing on main and PRs:

- uses: paladini/harness-score@v1
  with:
    min-level: '3'
    badge: 'harness-badge.svg'

If maturity falls below L3, the job fails and prints the gaps needed to recover (for example: missing sensors or CI coverage).

A practical rollout:

Week 1: min-level: '0' (observe)
Week 2: set min-level to your current level (prevent regressions)
Later: bump one level at a time as you add guides, sensors, and hooks

3) Add sticky PR comments (optional, highly recommended)

On pull_request events, the Action can compare the PR head against the base branch and update a single sticky comment:

on:
  pull_request:

permissions:
  contents: read
  pull-requests: write

jobs:
  harness:
    runs-on: ubuntu-latest
    concurrency:
      group: harness-score-${{ github.event.pull_request.number }}
      cancel-in-progress: false
    steps:
      - uses: actions/checkout@v4

      - uses: paladini/harness-score@v1
        with:
          min-level: '3'
          comment: 'true'
          badge: 'harness-badge.svg'

You need pull-requests: write — the Action cannot grant that for you.

The comment shows level movement (for example L2 → L3), score deltas, and newly passing / newly failing checks. That makes harness regressions visible in review, not only in a red X on the Checks tab.

4) Publish the badge in your README

The Action can write harness-badge.svg on every run. A common pattern is committing it to a badges branch (or uploading it wherever you host static assets), then embedding:

<img alt="Harness Score" src="https://raw.githubusercontent.com/<you>/<repo>/badges/harness-badge.svg" height="20">

You can also pin a static level badge from the docs site if you prefer not to auto-update.

More badge recipes: Show your maturity

Useful Action inputs

Input	Default	What it does
`min-level`	`0`	Fail when maturity is below this level (0–4)
`badge`	`harness-badge.svg`	SVG pill path (`empty` to skip)
`report`	(empty)	Write a Markdown report
`comment`	`false`	Sticky PR comment with score delta
`working-directory`	`.`	Subdirectory to scan (monorepos)
`version`	pinned release	`harness-score` npm version
`gate`	`maturity`	Gate on `maturity` (repo-only) or `effective`
`include-user-harness`	`false`	Include user-level harness paths in effective score
`config`	`.harness-score.json`	Custom config path

Outputs you can consume in later steps: level, level-name, percent.

Optional: repository config

If you need team policy (scopes, presets, per-check rules), add .harness-score.json at the repo root.

Example: keep CI gated on repository maturity, while still allowing local diagnosis with user-scope overlays:

{
  "scopes": {
    "user": true,
    "system": false
  },
  "gate": "maturity"
}

Customization is transparent: excluded checks are removed from both earned and available points (no free credit), and security checks for exposed credentials cannot be disabled.

What this does not claim

A high score means the infrastructure for reliable agent work exists:

context and rules
skills/commands
hooks/guardrails
sensors (tests/lint/types)
CI feedback
hygiene/safety

It does not mean your tests are good, your rules are true, or every runtime path honors the committed harness. That honesty is intentional — deterministic scanners should not pretend to judge vibes.

Full starter workflow

Copy-paste version with gate + PR comment + badge + report:

name: Harness maturity

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read
  pull-requests: write

jobs:
  harness:
    runs-on: ubuntu-latest
    concurrency:
      group: harness-score-${{ github.event.pull_request.number || github.ref }}
      cancel-in-progress: false
    steps:
      - uses: actions/checkout@v4

      - name: Scan AI harness maturity
        id: harness
        uses: paladini/harness-score@v1
        with:
          min-level: '3'
          comment: 'true'
          badge: 'harness-badge.svg'
          report: 'harness-report.md'

      - name: Upload report artifacts
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: harness-score
          path: |
            harness-badge.svg
            harness-report.md

Try it, then ratchet

Run npx harness-score@1.5.1 locally
Add the workflow with min-level: '0'
Set min-level to your current level to prevent silent regressions
Climb toward L3/L4 with the ranked fix list from the report

Links:

If you add this to a repo, comment with your starting level (L0–L4) and the first check that surprised you — those reports are the best way to harden the maturity model.

I Built an Ad-Free Open-Source Prep Pack for Wonderlic Select (and Other Hiring Cognitive Tests)

Fernando Paladini — Sun, 26 Jul 2026 17:55:14 +0000

If you have applied for a job lately — in tech or outside it — there is a decent chance you were asked to take a Wonderlic assessment. Maybe it was the classic 50 multiple-choice questions in 12 minutes. Maybe it was Wonderlic Select, which layers cognitive ability with personality and motivation sections and rolls them into a single job-fit score.

Either way, the format is brutal: roughly 14.4 seconds per question, no calculator, easy material under time pressure. The test is not really about whether you know calculus. It is about whether you can move fast, skip wisely, and stay calm when the clock is running.

And then you search for prep material online.

Most of what you find is a funnel: a few free sample questions, a paywall, ads, and upsells. That is fine if you want to buy a course. It is not fine if you just need honest practice before a screening round that might decide whether you get to the next interview.

So I built something different.

The problem is not just "study harder"

The Wonderlic has been used in hiring since 1936. You will see it in tech companies, healthcare, logistics, finance, and plenty of roles where employers want a short cognitive screen before investing more interview time.

The classic format — WPT-R — is 50 questions in 12 minutes. There are shorter variants like WPT-Q (30 questions / 8 minutes). Schools and nursing programs often use the SLE. Entry-level roles sometimes hit the WBST for basic verbal and math skills.

Then there is Wonderlic Select (formerly WonScore). That one is especially common in modern hiring pipelines:

~50 cognitive questions (same family as WPT-R)
Personality section (Big Five traits)
Motivation section (RIASEC / Holland codes)
Roughly 35 minutes total, with a combined job-fit score at the end

For software engineers, the cognitive bar is often higher — many employers expect a 30+ on the 0–50 scale — and Select adds a twist people do not expect: you cannot pass on cognitive ability alone. The personality and motivation sections matter too.

That combination catches candidates off guard. You might be strong at LeetCode and still stumble because you never practiced timed verbal analogies, mental math without a calculator, or the "answer honestly but strategically" mindset Select expects on the non-cognitive sections.

Most free resources online do not help much. They are either generic IQ trivia, outdated blog posts, or lead-gen pages dressed up as prep sites.

What I shipped: Awesome Wonderlic

Awesome Wonderlic is a curated, ad-free, open-source prep pack for Wonderlic-style hiring assessments.

Everything in the repo is genuinely free:

No ad-funded prep sites
No freemium funnels
No paid plans hiding behind a login wall

It is a dataset + curriculum + tooling project — not another timed quiz SaaS.

Content is dual-licensed:

CC BY-SA 4.0 for docs, questions, and practice tests
MIT for scripts and CI

What is inside the repo

150 original practice questions

The question bank has 150 original Wonderlic-style items across all six documented categories:

Verbal reasoning
Vocabulary
Arithmetic
Word problems
Logic and patterns
General knowledge

Each question lives in structured JSON with an answer key, difficulty rating (1–5), and a full explanation. The bank is validated in CI against a JSON Schema, so contributions stay consistent.

Exports are auto-generated to CSV, Markdown, and Anki TSV if you want flashcard drilling.

Full timed practice tests

There are two ready-to-run 50-question / 12-minute simulations with realistic category mix and difficulty curve:

Simulate real conditions: 12 minutes on a timer, no calculator, scratch paper only, no jumping around the test.

Need more? A Python script assembles unlimited randomized tests from the bank:

pip install -r scripts/requirements.txt
python scripts/build_practice_test.py --seed 7

Study guides and plans

The docs walk you through the parts most prep sites skip:

Test types explained — WPT-R, WPT-Q, Select, SLE, WBST
Scoring explained — the 0–50 scale, percentile intuition, role-based targets
Question categories — the six families with worked examples
Study guide and strategy — pacing, skip strategy, no-calculator tricks, error logs
Test-day tips — a practical checklist

Structured study plans:

For engineers facing Select specifically:

Wonderlic Select for software developers
14-day Select plan for software developers (plus a compressed 5-day variant)

One line from that guide worth repeating: the Wonderlic is not a knowledge test — it is a speed test over easy material. Select adds: you cannot pass on cognitive ability alone.

Curated external resources

The README also links vetted free material: official Wonderlic candidate FAQs and sample PDFs, the ICAR public cognitive item bank, open-source cognitive drill tools, and academic papers. The curation policy is strict — commercial prep sites are out of scope even when they offer free samples.

Start here (5 steps)

If the test is coming up, this is the fastest path in the repo:

Read What is the Wonderlic? and identify which variant you are facing.
Read How scoring works and set a realistic target for your role.
Skim the six question categories with worked examples.
Pick a study plan and follow it.
Drill the question bank and take the full timed practice tests.

That is enough to go from "I have no idea what this test looks like" to "I have timed reps and a strategy" in an evening.

For builders: it is also a structured dataset

If you are the kind of person who learns by building, the repo gives you more than markdown pages:

JSON Schema validation in CI (data/schema/question.schema.json)
Export scripts for CSV / Markdown / Anki
A practice-test generator with seed support for reproducible runs
Python 3 tooling with a single dependency (jsonschema)

You could fork it, build your own drill app, wire it into spaced repetition, or contribute new original questions that pass validation.

Why open source for this?

Hiring screens are already stressful. Prep material should not add a second paywall on top of the job search.

An open repo also means:

Transparency — every question has an explanation you can inspect
Community improvement — better wording, new items, translations of techniques
No lock-in — export to Anki, print a practice test, or generate your own

Contributions are welcome: original questions, better explanations, vetted links, tooling improvements. Read CONTRIBUTING.md first — it documents the curation rules and the question authoring guide.

Try it

Repo: github.com/paladini/awesome-wonderlic

If you are preparing for a Wonderlic or Select screen, start with a timed practice test this week. Log your misses by category. Repeat under real conditions. That beats reading about the test for the tenth time.

If you are hiring and use these assessments, I hope this gives candidates a fairer shot at showing up prepared — without paying for ads first.

Disclaimer: This project is not affiliated with, sponsored by, or endorsed by Wonderlic, Inc. "Wonderlic" is a trademark of Wonderlic, Inc., used here nominatively to describe the subject of this educational resource. Every question in the repository is an original work that mirrors the publicly documented format, categories, and difficulty curve of the test — not proprietary Wonderlic items.

Have you run into Wonderlic or Select in a hiring process recently? What caught you off guard — the pacing, the personality section, or something else? I would love to hear what would make the repo more useful.

DEV Community: Fernando Paladini

Run Local Audio Transcription with EchoTranscribe and Whisper

TL;DR

Prerequisites

Start the local backend

Launch the Tauri desktop app

Transcribe a file

Verify the path without transcribing a large recording

Why the local architecture works

Failure modes and security boundaries

FAQ

Does EchoTranscribe require a cloud API key?

Can I use it without a GPU?

Is main the same as the release?

Is it ready to expose as a shared service?

Takeaway

AI assistance disclosure

Self-Host Audio Stem Separation with Docker and Demucs

TL;DR

Prerequisites

Start the local service

Separate vocals with the API

Understand the model choices

Why the Compose mounts matter

YouTube input and its boundary

Failure modes to check first

Reproducible verification

FAQ

Does the audio leave my computer?

Can I run it without a GPU?

Is this a production-ready hosted service?

Takeaway

AI assistance disclosure

Style Active Admin 3 and 4 with One Rails Theme Gem

TL;DR

Prerequisites

Install the theme

Active Admin 4: build the Tailwind output

Active Admin 3: use the Sass entry point

Customize the palette without replacing the theme

Verify the installation

Why the version-aware generator matters

Failure modes and security boundaries

FAQ

Does one installation command support both Active Admin versions?

Do I need Node.js for Active Admin 3?

Can I use the theme with Propshaft?

Can I keep my own brand colors?

Takeaway

AI assistance disclosure

Trace AI Coding Changes to Requirements with Python and SARIF

What you will build

Prerequisites

1. Validate the evidence inputs

2. Generate reviewer and CI artifacts

3. See a failure instead of trusting a green result

Why the split between spec and change map matters

Failure modes to plan for

A valid JSON file can still describe weak evidence

A passing trace does not judge code quality

Inputs may contain sensitive data

A failed verification is intentionally not a test failure

Reproducible verification

FAQ

Does SpecTrace need an AI provider?

Does it replace tests?

Can it prove that an AI-generated change is correct?

Why generate SARIF?

Takeaway

Build a Typed Training Data Client in TypeScript with intervals-icu

TL;DR

Prerequisites

Install the stable client

Create the smallest useful client

Why service accessors matter

Add a typed activity query

API keys, OAuth, and retry behavior

Common failure modes

The client constructs but the request fails

A version 1 example no longer compiles

Is `main` the same as the release?