DEV Community: Fernando Paladini

Cross-Post a DEV.to Tutorial to Medium with a Formatting Check

Fernando Paladini — Thu, 13 Aug 2026 15:15:09 +0000

Cross-posting a technical tutorial is easy to start and surprisingly easy to get wrong. A URL import can leave code blocks split, headings as plain text, or metadata incomplete. The result may look acceptable at a glance while damaging the parts readers need most.

This tutorial shows a reviewable DEV.to to Medium workflow using publish-agents, an open-source TypeScript project by Fernando Paladini. Its medium-publisher package imports a public article through Medium's import flow, checks the editor against the source Markdown, and can repair a small set of common formatting problems.

TL;DR

Checkout the stable v0.2.3 release, build the @paladini/medium-publisher-mcp package, log in once, and create a Medium draft with publish-devto. Keep the default draft behavior while you inspect the title, code blocks, headings, lists, and metadata.

Prerequisites

You need:

Node.js 20 or newer.
A published DEV.to article with a public URL.
A Medium account that can create stories.
A terminal that can run npm and the browser installation step.

The package uses Patchright browser automation and a saved browser session. It does not use a Medium write API key. The project documents Medium UI changes as a compatibility risk, so treat the browser session and the resulting draft as reviewable state rather than an unattended guarantee.

Install the released source

The repository's v0.2.3 release is the stable reference for this walkthrough. Installing from that tag keeps the commands separate from later changes on the default branch.

git clone https://github.com/paladini/publish-agents.git
cd publish-agents
git checkout v0.2.3
npm install
npm run build -w @paladini/medium-publisher-mcp
npm link -w @paladini/medium-publisher-mcp

The build produces the CLI and MCP server from the package source. The package declares Node.js 20 or newer and uses patchright as its browser automation dependency. Its post-install step may install the bundled Chromium browser. If that step was skipped in your environment, run the browser installation command documented by Patchright before continuing.

Create a saved Medium session

medium-publisher login

Then check the session in JSON form:

medium-publisher session-check --json

The project stores browser state in an operating-system data directory by default. On Windows, the documented default is %LOCALAPPDATA%\medium-publisher\storageState.json. You can override it with MEDIUM_STATE_PATH or MEDIUM_PUBLISHER_HOME.

This is an important boundary: the saved state contains authentication cookies. Protect the directory like any other local credential store, do not commit it, and do not copy it into a CI artifact.

Import a DEV.to article as a draft

Use the one-shot command with --draft and --json:

medium-publisher publish-devto `
  --url "https://dev.to/your-name/your-tutorial" `
  --draft --json

The URL must point to a public article. The package fetches the DEV.to article through its public API, then opens Medium's official import route. The --draft flag matters because it leaves the final publication decision with you.

The JSON result includes a Medium URL and metadata details such as whether the title was set, which topics were selected, and whether a hero image was detected. Treat that URL as a draft inspection target until you have checked the actual editor.

Verify the imported editor

Open the returned draft URL in the browser, or use the package's structured extraction command:

medium-publisher extract `
  --url "https://medium.com/p/your-draft/edit" `
  --json

The extraction workflow is useful because it reports the editor outline and formatting flags. Check at least these points manually:

The title matches the DEV.to source.
Headings are rendered as headings, not literal Markdown text.
Each fenced code example is one code block with the expected language.
Lists, links, and paragraphs remain in the expected order.
The subtitle and topics describe the article without inventing claims.
No secrets or private URLs were imported accidentally.

The package includes a source review that compares the editor content with the DEV.to Markdown. It also has a security check for secret-like values and unexpected short links. These checks reduce risk, but they cannot replace reading the draft in the Medium editor.

Repair common formatting failures

If extraction identifies a problem, create an actions file and apply only the targeted fixes. For example:

[
  { "type": "removeEmptyCodeBlocks" },
  { "type": "mergeAdjacentCodeBlocks" },
  { "type": "promoteDemoteHeading", "blockIndex": 4, "level": 2 }
]

Apply it to the draft:

medium-publisher fix-draft `
  --url "https://medium.com/p/your-draft/edit" `
  --actions-file fixes.json `
  --json

Run extract again after the change. A repair is complete only when the editor and the source agree on the affected blocks. If the editor has changed since the release, stop and inspect the draft manually instead of repeatedly applying actions.

What success looks like

A successful draft run gives you a Medium editor URL, the expected title, readable code blocks, intact headings and lists, and metadata that you can explain. The command does not prove that Medium will preserve every future import. It gives you a repeatable starting point and evidence for a human review.

For a final pre-publication check, compare the draft with the original DEV.to article block by block. Pay particular attention to content after the first code block because malformed fences can make later paragraphs appear to be code. The repository's own test suite covers its formatting and metadata helpers, but your article is still the source of truth for the review.

MCP option for agent-assisted workflows

The same package exposes an MCP server. Register medium-publisher-mcp with your MCP client and use medium_publish_from_devto with publish: false for a draft-first flow. The project documents stdio configuration for clients such as Cursor and Claude Code.

An agent can prepare the URL and summarize the extraction result, but the account owner should approve login, external publication, and any formatting correction. Browser automation is an integration boundary, not a reason to remove human review.

Failure modes and limitations

The session is missing or expired

The CLI uses exit code 3 for a missing or expired session. Run medium-publisher login again. A two-factor challenge or bot check may require headed browser interaction.

The import hangs

The source article must be public because the workflow reads its public DEV.to representation. Confirm that the URL loads without authentication and that the article has been published.

Topics or selectors do not match

Medium's interface can change. The project waits for topic autocomplete and targets the current import and editor controls, but a future UI change can still break a selector. Use extract, inspect the draft, and report reproducible failures to the repository rather than publishing blindly.

The content contains sensitive data

Stop the workflow if the source or editor contains credentials, private links, or unexpected content. Delete the draft through Medium's controls as appropriate, rotate exposed credentials, and review the local browser-state directory.

FAQ

Does this need a Medium API key?

No. The documented workflow uses browser automation and a persistent login session.

Can it publish immediately?

The CLI supports publishing options, but this tutorial deliberately uses --draft. Review the imported editor before choosing a live publication action.

Does it import any URL?

The package supports public URL import, while the one-shot publish-devto path expects a public DEV.to article so it can compare the imported result with the source Markdown.

Is this a guarantee that Medium formatting will stay correct?

No. Medium UI changes, account challenges, and article-specific content can still require manual intervention.

AI assistance disclosure

AI assistance was used to organize this tutorial and check its wording. Commands, version references, workflow boundaries, and limitations were checked against the public publish-agents repository, its v0.2.3 release, and the package's documented source behavior.

Takeaway

Cross-posting is safer when import, repair, and publication are separate decisions. Use publish-devto --draft, inspect the real Medium editor, rerun extraction after any fix, and publish only after the source and destination agree.

Have you found a Medium import failure that a block-level source review catches earlier than a visual skim?

Build a Citation-Checked Research Report in Python with Evidence Graph Studio

Fernando Paladini — Wed, 12 Aug 2026 18:28:51 +0000

Polished technical writing can still hide a basic failure: a sentence has no source, a citation points to a missing record, or two sources disagree and the draft does not show it.

If you are reviewing AI-assisted research, a pile of links is not enough. You need to see which source supports which claim, which claims need review, and what a writer can cite in the final report.

This tutorial uses Evidence Graph Studio, a small MIT-licensed Python project that turns a JSON research dossier into a claim-to-source graph, a Markdown report, a citation pack, JSON graph data, and Mermaid source. It is deterministic and uses only the Python standard library.

TL;DR

Create a dossier containing sources, claims, and evidence links. Run the validator and builder. A successful build exits with status 0 when every claim is supported. A dossier that needs review exits with status 2, so a CI job can stop before an unsupported claim reaches publication.

Prerequisites

You need Python 3.10 or newer, Git, and a shell. The project does not require a database, API key, model download, or network access at runtime.

Clone the repository and enter it:

git clone https://github.com/paladini/evidence-graph-studio.git
cd evidence-graph-studio

The repository currently documents version 0.1.0 in pyproject.toml, requires Python 3.10 or newer, and is released under the MIT license. The commands below target the current default branch because the project has no GitHub release.

Run the bundled example

The repository includes a dossier about AI agent reliability. Set PYTHONPATH to the source directory, then validate the input before generating output:

$env:PYTHONPATH = "$PWD\src"
python -m evidence_graph_studio validate `
  --dossier examples\ai-agent-reliability-dossier.json

The validator checks the dossier structure without writing reports. The bundled example contains three claims and three sources.

Now build the complete evidence pack:

python -m evidence_graph_studio build `
  --dossier examples\ai-agent-reliability-dossier.json `
  --out build\evidence-report.md `
  --graph-out build\evidence-graph.json `
  --citations-out build\citation-pack.md `
  --mermaid-out build\evidence-graph.mmd

The command writes four artifacts:

build/evidence-report.md contains summary counts and per-claim findings.
build/evidence-graph.json preserves the graph for downstream tools.
build/citation-pack.md groups citations by source and claim.
build/evidence-graph.mmd can be rendered in documentation or a pull request.

The documented example produces 3 supported, 0 need review and exits successfully.

Understand the dossier shape

The input is deliberately explicit. A source has an ID, URL, summary, tags, and optional quotes. A claim has an ID, text, required tags, and evidence entries that point back to source IDs.

Here is a minimal dossier:

{
  "project": "Release review",
  "sources": [
    {
      "id": "source.release-notes",
      "title": "Release notes",
      "url": "https://example.com/release-notes",
      "summary": "The release adds a validation command.",
      "source_type": "documentation",
      "tags": ["release"],
      "quotes": ["The validation command checks the input dossier."]
    }
  ],
  "claims": [
    {
      "id": "claim.validation",
      "text": "The tool can validate a dossier before building reports.",
      "required_tags": ["release"],
      "evidence": [
        {
          "source_id": "source.release-notes",
          "stance": "supports",
          "note": "The release notes describe the validation command.",
          "quote": "The validation command checks the input dossier."
        }
      ]
    }
  ]
}

Evidence uses one of three stances: supports, contradicts, or context. That distinction matters. A source that mentions a topic is not automatically support for a claim, and a contradiction should remain visible for review rather than being silently discarded.

Optional links can express relationships between claims, such as depends_on. The output graph therefore captures more than a flat bibliography: it records the reasoning structure that a reviewer needs to inspect.

Verify the result in a repeatable way

The project includes seven unit tests. Run them from the repository root:

python -m unittest discover -s tests

For a practical check, assert that the generated report and citation pack exist, inspect the summary, and review the Mermaid graph. A useful CI policy is to fail when the build exits with status 2. That preserves the distinction between a valid report and a report that was generated but still needs human review.

You can also inspect the JSON graph in a later step without reparsing Markdown. That makes the output suitable for a documentation pipeline, a pull request check, or a custom review interface.

Why this works

The design makes support a data relationship instead of a formatting convention. Each evidence item names its source and stance. The builder can then detect missing source IDs, unsupported claims, contradictory evidence, and missing required topic tags consistently.

This is especially useful for AI-assisted drafting. A language model can help propose claims or source notes, but the dossier gives a reviewer a concrete object to validate. The generated Markdown is an output of that review model, not the model's memory of where a statement came from.

Failure modes and boundaries

An exit status of 2 is not a crash. It means the report contains claims that need review. Treat it as a gate in automation, not as proof that the sources are false.

The tool checks the structure and relationships you provide. It does not fetch URLs, verify that a quote is authentic, measure source quality, or decide whether a claim is true. Those remain research and editorial responsibilities.

The path is local and deterministic, but the input can still contain sensitive material. Do not place credentials, private customer data, or confidential research in a dossier that will be committed or uploaded. The MIT license permits reuse, but it does not change your obligations for the sources and data you process.

FAQ

Does it use an AI model?

No. Version 0.1 is documented as deterministic and uses the Python standard library.

Does it need internet access?

No runtime network access is required. The dossier stores source metadata and URLs, while the tool checks the relationships locally.

Can it replace fact checking?

No. It makes missing, conflicting, or incomplete support visible. A person still needs to inspect the source and decide whether the claim is accurate.

Can I delete old files automatically?

The current project is an evidence graph builder and report exporter. It does not describe a content deletion workflow. Keep cleanup and retention policy outside the build step until you have reviewed your own requirements.

Takeaway

If a research workflow ends with a Markdown draft and a loose list of URLs, the review boundary is hard to see. Evidence Graph Studio gives each claim an explicit relationship to its sources and turns unresolved support into a machine-checkable result.

Start with the bundled example, then adapt the dossier format to one small article or research brief. Keep the validator in CI and require human review whenever the build reports claims that need review.

I used AI assistance to organize and edit this tutorial. The commands, project behavior, version details, and limitations were checked against the public repository and a local run of its documented example.

What evidence relationship would be most valuable in your own review workflow: missing support, contradictions, required topic coverage, or claim dependencies?

Build Typed Gear-List Automation with the LighterPack SDK

Fernando Paladini — Tue, 11 Aug 2026 12:37:49 +0000

Planning a gear list in a browser is convenient until the list becomes data you need to generate, review, or update repeatedly. A spreadsheet can hold the rows, but it does not automatically create categories, preserve LighterPack's rules, or calculate the result you actually see in the app.

This tutorial shows a small TypeScript workflow built with @paladini/lighterpack. It creates a complete backpacking list in one batch operation, reads the resulting totals, and demonstrates the safety boundaries you need to understand before automating writes to a personal account.

TL;DR

The SDK is an unofficial, ESM-only TypeScript client for LighterPack. It requires Node.js 20 or newer, uses your normal LighterPack username and password, and has no runtime dependencies. Its batch.createListWithItems() method can scaffold categories and items in one save round-trip.

The example below is a real API shape from the current 0.1.0 package and repository. Replace the placeholder credentials with environment variables, run it against an account you control, and inspect the returned totals before adding more automation.

Prerequisites

You need:

Node.js 20 or newer
A LighterPack account you are allowed to modify
A new TypeScript project using ESM
Credentials supplied through the environment, not committed to source control

The SDK is published under the MIT license. It is not affiliated with or endorsed by LighterPack. The project documents the package as an unofficial client that talks to the web application's own API.

Create a project and install the package:

mkdir typed-gear-list
cd typed-gear-list
npm init -y
npm install @paladini/lighterpack
npm install --save-dev tsx typescript

The package metadata declares "type": "module", exposes TypeScript declarations, and currently publishes version 0.1.0 as the npm latest tag. The repository's README and package metadata are the source for those details.

Create a complete list in one call

Set credentials in your shell. PowerShell users can run:

$env:LIGHTERPACK_USERNAME = "your-username"
$env:LIGHTERPACK_PASSWORD = "your-password"

Create index.ts:

import { LighterPackClient } from '@paladini/lighterpack';

const username = process.env.LIGHTERPACK_USERNAME;
const password = process.env.LIGHTERPACK_PASSWORD;

if (!username || !password) {
  throw new Error('Set LIGHTERPACK_USERNAME and LIGHTERPACK_PASSWORD first.');
}

const lp = new LighterPackClient({ username, password });

const detail = await lp.batch.createListWithItems({
  name: 'Weekend shelter system',
  description: 'A small example generated from TypeScript.',
  categories: [
    {
      name: 'Shelter',
      items: [
        { name: 'Two-person tent', weight: 1450, weightUnit: 'g', price: 249.99 },
        { name: 'Groundsheet', weight: 180, weightUnit: 'g', price: 24.5 },
      ],
    },
    {
      name: 'Sleep system',
      items: [
        { name: 'Sleeping bag', weight: 780, weightUnit: 'g', price: 189 },
        { name: 'Sleeping pad', weight: 420, weightUnit: 'g', price: 99 },
      ],
    },
  ],
});

console.log({
  listId: detail.listId,
  name: detail.name,
  weightGrams: detail.totals.weightGrams,
  price: detail.totals.price,
});

Run it with npx tsx index.ts.

The expected result is an object containing the created list ID, its name, and computed totals. The four item weights sum to 2,830 grams. The price total should be 562.49 in the account's configured currency representation, subject to the service's own handling of optional fields.

This example uses grams explicitly. The SDK accepts g, oz, lb, or kg as input units and returns weightGrams at its output boundary. Making the unit explicit is useful when data comes from different sources and avoids silently mixing ounces and grams.

Verify the result with a fresh read

The client keeps a library cache for the lifetime of the instance. That makes several reads efficient, but a script that needs to confirm server state can call refresh() and then fetch the list again:

await lp.account.refresh();
const lists = await lp.lists.list();
const created = lists.find((list) => list.listId === detail.listId);

if (!created) {
  throw new Error(`List ${detail.listId} was not found after refresh.`);
}

console.log(`Verified ${created.name}: ${created.totals.weightGrams}g`);

For a disposable test account, add a cleanup step after verification:

await lp.lists.delete(detail.listId);
console.log('Deleted the test list.');

Do not add that deletion to a production workflow unless the list is intentionally disposable. The SDK documents deletion as irreversible and also protects the account from deleting its only list.

Why the batch API matters

LighterPack does not expose a granular CRUD API for each list mutation. The SDK documentation describes the library as one JSON document saved through POST /saveLibrary with an optimistic-concurrency sync_token.

That implementation detail explains the design of the client. Every mutation goes through one sync engine that loads the library, applies a change to a clone, and saves the result. If another writer changes the library first, the engine refetches and retries once. A second conflict becomes a typed SyncConflictError instead of silently overwriting newer data.

Calling items.add() repeatedly is still valid, but batch.addItems(), batch.createListWithItems(), and batch.updateItems() are better fits for generated data because they group related changes into one save operation. The repository's batch API implementation is the precise reference for the accepted fields and validation behavior.

Update many items safely

After importing a gear inventory, you may need to mark worn items or adjust quantities. Flags belong to an item's placement in a category, so the batch update accepts a categoryId when flags are involved:

const updated = await lp.batch.updateItems([
  {
    itemId: 123,
    categoryId: 456,
    flags: { worn: true, qty: 1 },
  },
  {
    itemId: 789,
    fields: { weight: 410, weightUnit: 'g' },
  },
]);

console.log(updated.map((item) => ({ name: item.name, weight: item.weightGrams })));

The SDK enforces documented rules such as requiring weightUnit whenever a weight is changed. It also models worn and consumable as mutually exclusive flags. These checks happen before the save, so an invalid input should fail without a partial library update.

Authentication and security boundaries

There is no separate LighterPack API-key system in this SDK. Authentication uses the regular account username and password. The client keeps the resulting session cookie in memory for its lifetime and does not provide a persistent token to revoke individually. The project's README recommends changing the account password if access must be cut off.

Treat credentials as secrets. Use environment variables or a local secret manager, exclude .env files from Git, and never paste a real password into a tutorial or issue. For a self-hosted LighterPack deployment, the client accepts a baseUrl option, but you must verify that the instance is trusted and that its API behavior matches the client assumptions.

The SDK also supports image uploads and public share-link generation. Both can create external effects, so add explicit confirmation and cleanup rules before exposing them to an automated job.

Common failure modes

The command fails before any network request

Check the environment variables and input validation first. Bad units, malformed colors, invalid stars, and missing category IDs are represented by typed validation errors.

A save reports a synchronization conflict

Another browser tab or process may have changed the library. Retry from fresh state only after deciding which writer should win. The SDK already retries one stale-token conflict; a second conflict is surfaced as SyncConflictError.

The output is not what the web UI displays

The SDK treats weights as grams at its input and output boundaries, while LighterPack can display another unit in the UI. Compare weightGrams and the account's display settings instead of comparing formatted strings.

The example creates data in the wrong account

Stop and inspect the configured username before performing another write. For repeatable tests, use a dedicated account and delete only the lists created by that test.

FAQ

Is this an official LighterPack SDK?

No. It is an unofficial open-source client maintained in paladini/lighterpack-sdk. Verify that its assumptions still match your target service before relying on it.

Can I use JavaScript instead of TypeScript?

Yes. The package ships ESM JavaScript, and the TypeScript declarations are optional at runtime. TypeScript is useful here because list, category, item, unit, and error shapes become part of the editor feedback loop.

Does the tutorial run without credentials?

The repository's unit tests run without a live account. The end-to-end example requires credentials because it creates and modifies real remote data.

Takeaway

The useful boundary is not a clever wrapper around HTTP. It is a typed workflow that makes list structure, units, batch writes, conflict handling, and credential boundaries visible in code. Start with a disposable account, create one small list, refresh it, verify the totals, and only then automate larger imports.

Have you found a safer input format for generating backpacking lists - CSV, a typed JSON file, or a spreadsheet export? Share the validation and cleanup rules that made your workflow trustworthy.

AI assistance disclosure

AI assistance was used to help organize and edit this tutorial. The repository README, package metadata, implementation, tests, and published package metadata were checked against the claims and examples before publication.

Detect AI-Built Web Pages with a Chrome Extension Heuristic Scanner

Fernando Paladini — Mon, 10 Aug 2026 12:36:53 +0000

TL;DR

You can inspect a page for signs of AI-assisted generation without uploading its HTML to a server. This tutorial walks through Vibe Code Detector, an open-source Chrome extension that runs weighted heuristics in the browser and reports a score with the detected factors.

The useful engineering idea is not the label. It is the separation between observable signals, a transparent scoring model, and a user interface that lets you inspect why a result happened.

The problem: a score is easy, an explainable score is harder

Browser extensions that inspect page structure face an awkward tradeoff. A simple rule can find a marker such as data-radix-*, a Lucide SVG, or a generator meta tag. But any one marker is weak evidence. Modern sites can use the same libraries for ordinary reasons, and a generated site may remove or change those markers.

Vibe Code Detector combines several signals instead of treating one match as proof. Its canonical factor list includes utility-class density, Shadcn or Radix markers, Lucide iconography, AI IDE markers, platform signatures, prompt-like comments, provider metadata, placeholder text, and other structural clues. Each factor has a weight, and the result exposes the individual detections.

That makes the extension useful as a forensic hint, not as an authorship detector. The distinction matters: the project documentation describes heuristic analysis, while the implementation can only observe the current document and its accessible markup.

Prerequisites

You need:

Node.js 20 or a compatible current Node.js installation
npm
Google Chrome or another Chromium browser that supports Manifest V3
A page you are allowed to inspect

The repository is released under the MIT License. The current main branch reports version 1.0.0 in both package.json and extension/manifest.json.

Build the extension from source

Clone the public repository and install its locked dependencies:

git clone https://github.com/paladini/vibe-code-detector.git
cd vibe-code-detector
npm ci

Build the extension and run the TypeScript check:

npm run lint
npm run build

The lint script runs tsc --noEmit. The Vite build writes the extension assets into extension/, including the popup page and bundled assets. The release workflow uses the same build command before packaging extension/ into a zip.

To load the result locally, open chrome://extensions, enable Developer mode, choose Load unpacked, and select the repository's extension/ directory. The manual installation path is also documented in the project README.

How the scanner works

The implementation keeps its factor definitions in src/lib/vibe-detector.ts. The same analysis function is used by the web preview and popup, while the content script contains an inlined copy because browser content scripts do not use the project's module imports directly.

The main path is straightforward:

Read the active document's HTML and element structure.
Count utility classes and compare the count with the number of elements.
Check for known Shadcn, Radix, Lucide, IDE, and platform markers.
Walk comment nodes for prompt-like or generated-by text.
Add the weights of detected factors.
Clamp the score to 100 and return the factor list.

For example, the utility-density rule counts whitespace-separated classes on elements and marks the factor when the average exceeds 4.5, or when the HTML includes the tw- prefix. The Shadcn and Radix rule requires at least three markers from a small list that includes bg-background, text-foreground, data-radix-, data-state=, rounded-xl, and border-input.

The result is intentionally inspectable. A caller receives a score plus factors shaped like this:

export interface VibeResult {
  score: number;
  factors: VibeFactor[];
}

This structure is more valuable than a bare boolean because it supports review. Someone examining a high score can ask which signals fired and whether those signals make sense for the page.

Verify the behavior without trusting the label

Use two pages with different characteristics. First, inspect a normal documentation or application page that uses a component library. Then inspect a page that clearly contains one or more generator markers. Compare the factor list, not just the final score.

The project has a practical constraint: extension/content.js must stay synchronized with src/lib/vibe-detector.ts. If you change a heuristic, update both paths and rebuild. Otherwise the preview and the loaded extension can disagree even though the TypeScript source looks correct.

You can also verify the packaged output by checking that the build produced extension/popup.html and the generated JavaScript and CSS assets. The repository's release workflow runs npm ci, npm run build, checks that the package and manifest versions match, then creates a zip and SHA-256 checksum.

Failure modes and security boundaries

A high score is not proof

Tailwind, Radix, Lucide, and motion libraries are popular outside AI-generated projects. Conversely, a site can be generated with an AI tool and remove the visible markers. Treat the score as a collection of clues. Do not use it as evidence of who wrote a page or as an automated moderation decision.

The scan is document-local

The core function receives a Document and reads its DOM, HTML, and comments. It does not establish provenance, inspect a private repository, or recover an author's workflow. Results can change after client-side rendering, navigation, or a site redesign.

Permissions still matter

The manifest requests activeTab and scripting, and its content script matches <all_urls>. Install the extension only from a source you trust, review permission changes, and inspect the code before loading an unpacked build. The repository recommends the Chrome Web Store listing for normal installation, while source loading is useful for development and review.

Dependency health is separate from scanner logic

In a fresh checkout on August 10, 2026, npm ci completed and reported 19 audit findings: 2 low, 7 moderate, 9 high, and 1 critical. That result is not proof that the extension is exploitable, but it is a reason to review the dependency tree before distributing a build. Run npm audit yourself and reassess the result as dependencies change.

FAQ

Does it detect whether a human or AI wrote a page?

No. It detects implementation and markup signals that may correlate with AI-assisted tools. The score is heuristic evidence about the page, not an authorship verdict.

Does the extension upload the page?

The documented analysis function operates on the active page's Document. Review the current repository and manifest before installing any version, especially if future releases add network features.

Can I add another AI tool signature?

Yes. Add a narrowly defined marker or factor to the canonical TypeScript implementation, mirror the change in extension/content.js, then run npm run lint and npm run build. A good contribution should include a reason the signal is useful and a note about false positives.

Takeaway

The strongest part of this project is its boundary: it turns a vague question about a web page into a visible list of weighted, testable signals. That does not make the conclusion certain. It makes the reasoning inspectable, which is the better property for a browser tool that deals with ambiguous evidence.

AI assistance disclosure: I used an AI assistant to help organize this tutorial and check the documented build path. The repository behavior, commands, permissions, and limitations were verified against the public source and a fresh local build.

What additional page signal would you test first, and how would you measure whether it adds useful evidence without increasing false positives?

Build an Offline Spatial Reasoning Trainer with OpenFold

Fernando Paladini — Sun, 09 Aug 2026 12:40:25 +0000

Build an Offline Spatial Reasoning Trainer with OpenFold

TL;DR

If you want to practice mental rotation without uploading attempts to a hosted service, OpenFold is an interesting open-source example. It generates cube-net folding problems locally, renders them with Three.js, stores practice telemetry in IndexedDB, and exposes a React web app. This tutorial checks out the current main branch, builds the app, runs its test suites, and explains where its offline boundary comes from.

The problem: spatial practice is often difficult to inspect

Spatial reasoning practice needs more than a collection of static images. A useful exercise should generate new problems, distinguish equivalent cube rotations from genuinely different answers, give feedback, and let you review progress.

That creates an engineering problem: the generator, 3D view, answer validation, and local history must agree. If they use different geometry rules, a visual answer can look correct while the checker rejects it. If the app sends attempts to a server, the learner also loses a simple privacy boundary.

OpenFold addresses that problem as a local-first educational simulator. Its README describes procedural cube-net exercises, a TypeScript core, a Three.js renderer, a React web app, IndexedDB telemetry, and a Rust desktop shell. The repository is public and MIT licensed.

This walkthrough uses the repository's current main branch. The README and changelog describe a v1.0.0 scope, but the v1.0.0 Git ref was not resolvable during verification, so do not treat that label as a downloadable release here.

Prerequisites

You need:

Node.js 20 or newer.
pnpm 10 or newer.
Git.
A modern browser if you want to run the web app.

The Node and pnpm requirements come from the repository README and root package metadata. The desktop wrapper additionally requires a Rust toolchain, but it is not needed for the web build.

1. Check out and install the project

Clone the repository and install its pinned dependency graph:

git clone https://github.com/paladini/OpenFold.git
cd OpenFold
pnpm install

The workspace contains three relevant packages: @openfold/core, @openfold/render, and @openfold/web. The core and render packages are private workspace packages rather than published npm packages, so a source checkout is the normal path for this tutorial.

2. Build the browser application

Run the workspace build:

pnpm -w build

This compiles the TypeScript packages and creates the Vite production bundle for the web app. To try the application locally, start the documented development server:

pnpm --filter @openfold/web dev

Open the local URL printed by Vite. The browser version does not require an account or an API key. The app's storage layer uses IndexedDB for local sessions and attempts, and the desktop bridge is a no-op in a plain browser.

3. Understand the generated problem

The most useful boundary in OpenFold is the core package. Its public generateProblem function accepts a seed and either generation parameters or a difficulty preset. Internally, the current implementation:

validates the seed and resolves the preset;
creates a deterministic random-number generator;
generates a cube net;
folds the net into a cube state;
creates non-equivalent distractors;
shuffles the answer pool; and
returns the correct answer index plus metadata for the distractors.

That sequence matters because the renderer and the answer checker can share the same folded representation. The code also retries generation when a distractor set cannot be built, then throws a GenerationError after its bounded redraw limit. A bounded failure is easier to test and diagnose than an infinite retry loop.

The current core API is documented directly in packages/core/src/index.ts. The implementation exports helpers for canonicalization, equivalence checks, presets, net generation, and seeded random numbers, which makes the geometry rules testable without opening a browser.

4. Verify the important behavior

Run the checks used by the repository's workspace scripts:

pnpm -w typecheck
pnpm -w lint
pnpm -w test

In my source checkout of the current main branch, the checks completed successfully. The core package reported 112 passing tests, the render package reported 76, and the web package reported 264.

The tests cover more than whether functions return objects. The core suite checks that alternatives are pairwise non-equivalent, that the correct answer is not positionally biased across seeded samples, and that generated problems remain valid across difficulty presets. The render suite compares its folded state with the core result. The web suite exercises rounds, keyboard-only play, local persistence, dashboards, and training explanations.

The repository also defines a Playwright configuration for browser tests and an accessibility audit. Those checks are separate from the fast workspace test command and require the browser test setup, so a green unit and integration test run should not be described as a complete cross-browser or WCAG certification.

Why the offline boundary is useful

OpenFold's local-first design is concrete rather than just a marketing label:

The web app persists attempts through IndexedDB.
The README describes no network calls for problem generation and local training data.
There are no user accounts or cloud-sync features in the documented v1 scope.
The desktop bridge exists for the native shell, while a browser can run without it.

This gives a learner a clear operational model: install the code, open the app, practice, and keep the resulting history in the local browser profile. The tradeoff is equally important. Local storage is not a backup service. Clearing browser data, changing profiles, or uninstalling a portable desktop build can make history unavailable unless you export it first.

Failure modes and limitations

The project documentation lists several limits that should shape your expectations:

The exercise type is cube-net folding. It is not a general spatial-ability trainer.
Difficulty uses deterministic tiers rather than adaptive IRT.
The web experience is English-only at the documented scope.
The desktop distribution is portable rather than a signed native installer.
Cross-engine behavior on macOS and Linux webviews still needs manual verification according to the release notes.
The production web bundle emits a large-chunk warning during Vite build. That is a packaging optimization issue, not evidence that the build failed.

The security boundary is also narrow. Offline generation and local IndexedDB storage reduce the need to send practice data elsewhere, but they do not protect a compromised machine or browser profile. The repository's own release checklist calls for reviewing credentials, path traversal, XSS, dependency licenses, and audit results. Those are review tasks, not guarantees supplied by the README.

FAQ

Is OpenFold available as an npm package?

The workspace packages are marked private in their package metadata. Use the repository checkout and pnpm workspace commands for development.

Do I need Rust to try the app?

No. Rust is required for the desktop wrapper. The React and Vite web app can be built and served with Node.js and pnpm.

Does a seed make every visual result identical everywhere?

The core generator is seeded and tested for deterministic geometry, but the changelog distinguishes web verification from manual verification of other webview engines. Treat cross-platform visual equivalence as a claim to test on the target platform.

Is local storage the same as private storage?

No. It means the application is designed to keep data on the local device. Anyone or any software with access to that browser profile or machine may still access it.

Takeaway

OpenFold is a compact case study in making an educational simulator inspectable: deterministic generation, shared geometry rules, local telemetry, and tests that connect the core to the UI. Start with the web workspace, run the typecheck, lint, build, and test commands, then inspect the core package before changing the visual layer.

The project describes a v1.0.0 scope, but its release tag was not verifiable in this run. If you use OpenFold, pin the commit you tested and keep that distinction visible in your own notes.

What would you improve first: adaptive difficulty, additional spatial exercise types, or a more portable desktop release process?

AI assistance disclosure

This tutorial was researched and edited with AI assistance. Repository facts, commands, source links, and verification results were checked against the public OpenFold repository and a local source checkout before publication.

Fetch Daily Reflections from Node.js with an Unofficial AA API Client

Fernando Paladini — Sat, 08 Aug 2026 12:36:43 +0000

Many small Node.js scripts start as one HTTP request and become awkward as soon as they need a date, a language, a reusable type, and a useful error message.

This tutorial uses aa-daily-reflections, an MIT-licensed open-source Node.js library, to build that boundary in a few minutes. The package exposes a typed DailyReflections class and an aa-daily command. It fetches Daily Reflections content from the public AA.org API, so the useful engineering lesson is not just how to print a result. It is how to keep input validation, network access, parsing, and attribution visible in a small client.

TL;DR: Install aa-daily-reflections, use getReflection(month, day) for a deterministic date, choose en, es, or fr, and treat the upstream service and its content rules as part of your application boundary.

Prerequisites

You need:

Node.js 16 or newer and npm 8 or newer.
A terminal with network access.
A legitimate personal, educational, or recovery-support use for the returned content.

The package metadata currently declares version 1.0.1, MIT licensing, and support for Windows, macOS, and Linux on x64 or arm64. Node.js 18 or newer is a simpler choice because it provides the native fetch implementation used by the library. On Node.js 16, the project can fall back to node-fetch when it is available.

Install and inspect the CLI

Create a small project and install the package:

mkdir daily-reflection-demo
cd daily-reflection-demo
npm init -y
npm install aa-daily-reflections

The package includes the aa-daily executable. Before making a request, inspect its documented options:

npx aa-daily --help

The CLI supports today's reflection, a specific MM/DD date, and the en, es, and fr language codes. The help command is a useful first smoke test because it exercises the installed package without contacting the upstream service.

To fetch a specific date in English, run:

npx aa-daily 06/25

The output is formatted for a terminal and may include a title, quote, reference, reflection text, and copyright information. The command is a convenience layer. The class API is the better fit when another program needs structured data.

Use the typed API from JavaScript

Add a file named index.cjs:

const { DailyReflections } = require('aa-daily-reflections');

async function main() {
  const client = new DailyReflections('en');
  const reflection = await client.getReflection(6, 25);

  console.log({
    date: reflection.date,
    title: reflection.title,
    reference: reflection.reference,
    copyright: reflection.copyright,
  });
}

main().catch((error) => {
  console.error(error.message);
  process.exitCode = 1;
});

Run it with:

node index.cjs

The important choice is getReflection(6, 25), rather than embedding a URL in your application. The library validates the month and day, builds the upstream URL, performs the request, parses the response, and returns a DailyReflection object. That gives a caller one narrow async boundary and one predictable place to handle failure.

For a date-driven application, getToday() uses the machine's current local date:

const client = new DailyReflections('en');
const today = await client.getToday();
console.log(`${today.monthName} ${today.day}: ${today.title}`);

If your application runs in a different timezone from the person reading it, pass an explicit month and day instead. The library's getToday() reads the JavaScript runtime's current date; it does not accept a timezone argument.

Switch languages without duplicating clients

The supported language type is intentionally small: en, es, or fr. You can select a language at construction time or change it before a later request:

const { DailyReflections } = require('aa-daily-reflections');

async function printTitles() {
  const client = new DailyReflections('en');

  for (const language of ['en', 'es', 'fr']) {
    client.setLanguage(language);
    const reflection = await client.getReflection(6, 25);
    console.log(`${language}: ${reflection.title}`);
  }
}

printTitles().catch((error) => {
  console.error(`Could not load reflections: ${error.message}`);
  process.exitCode = 1;
});

This example makes the package's stateful design visible. setLanguage() changes the language for future requests on that instance. If concurrent requests need different languages, use separate instances so one operation cannot change another operation's configuration.

Add a failure boundary

There are two different kinds of invalid input to handle. A month outside 1 through 12 is rejected, and a day greater than the valid number for a month is rejected before the network request. Network and upstream HTTP failures happen later.

const { DailyReflections } = require('aa-daily-reflections');

async function readDate(month, day) {
  const client = new DailyReflections('en');

  try {
    return await client.getReflection(month, day);
  } catch (error) {
    if (error.message.includes('not valid for month')) {
      throw new Error('Choose a real calendar date.');
    }

    throw new Error(`The reflection service could not be reached: ${error.message}`);
  }
}

readDate(2, 30)
  .then((reflection) => console.log(reflection.title))
  .catch((error) => {
    console.error(error.message);
    process.exitCode = 1;
  });

The project wraps fetch failures with Failed to fetch daily reflection. Its HTTP client sends an Accept: application/json header and throws when the upstream response is not successful. That is enough for a small script, but a production integration may want retry policy, timeout handling, structured logging, and a cache owned by the application.

Verify the result reproducibly

Use a fixed date for a smoke test rather than today's date. That lets you verify the same input path repeatedly:

npx aa-daily -d 06/25 -l es

Then verify the local validation path without depending on a successful network request:

npx aa-daily -d 02/30

The second command should fail with an invalid-date error before a valid reflection is printed. Do not assert an exact quote or reflection body in an automated test unless you have permission to store that content and are prepared for upstream changes.

Why this boundary is useful

The library separates four concerns: date helpers validate inputs, URL helpers construct the request, an HTTP client handles fetch and status errors, and a parser converts the upstream response into the DailyReflection shape. The public class then exposes only the operations an application needs: get today's item, get a date, change language, and inspect the current language.

That structure is small enough to understand and useful enough to reuse. It also leaves the right responsibilities with the caller. Your application decides how to schedule requests, cache results, display content, and respond when the upstream service is unavailable.

Limitations and security boundaries

This is an unofficial client. It is not endorsed by Alcoholics Anonymous.
The library accesses content from the public AA.org API. Respect the source, its terms, copyright, and reasonable request rates.
The software is MIT licensed, but the Daily Reflections content is separately copyrighted by Alcoholics Anonymous World Services, Inc. The library license does not grant permission to republish that content.
The package does not provide authentication, an API key, retries, caching, or a documented service-level guarantee.
Never put account credentials or unrelated secrets into this client. It only needs the public upstream request described by the package.
Treat returned text as untrusted external data. Escape it for HTML, logs, or other output formats as appropriate.

FAQ

Does this package need an API key?

No API key is documented. It requests the public upstream service, so rate limits and availability still apply.

Can I use TypeScript?

Yes. The package publishes declarations and exports DailyReflection and Language types.

Does `getToday()` use UTC?

It uses the JavaScript runtime's local date. Use an explicit month and day when timezone behavior matters.

Is the content safe to republish in my app?

Do not assume that. Review the source's terms and copyright position. The repository explicitly separates its MIT software license from the copyrighted AA content.

Takeaway

aa-daily-reflections is a compact example of a good application boundary: validate inputs before I/O, return typed data, expose the CLI and API separately, and document the legal and operational limits around upstream content. Start with a fixed-date smoke test, then add your own timeout, cache, and output policy if the workflow grows.

Have you built a small API wrapper where the hardest part was not the request itself, but making the upstream limits clear to every caller?

AI assistance disclosure: This tutorial was researched and drafted with AI assistance. The repository documentation, package metadata, source files, and CLI help were checked against the current public project before publication.

Build a Deterministic Multi-Agent Pipeline with A2A in Python

Fernando Paladini — Thu, 06 Aug 2026 12:36:58 +0000

Multi-agent examples often jump straight to models, tools, and production claims. That makes it difficult to see what the protocol is doing. Before adding an LLM, it is useful to watch a small system discover specialists, delegate a task, and return a result that you can inspect.

This tutorial uses A2A Orchestration Lab, an open-source Python project by Fernando Paladini. It starts three local agents: an orchestrator, a researcher, and a writer. The researcher and writer are deterministic stubs, so the example isolates the Agent2Agent (A2A) communication flow from model behavior.

The result is a runnable research-to-write pipeline that helps explain where A2A fits next to the Model Context Protocol (MCP).

TL;DR

Install the lab with uv, run its demo command, and inspect the three local Agent Cards and the delegated result. The project is a learning lab, not a production runtime. That is a feature for this tutorial because every moving part remains visible.

Prerequisites

You need:

Python 3.12 or newer.
uv for environment and dependency management.
A terminal with network access for the initial dependency download.

The repository declares version 0.1.0, requires Python >=3.12, and depends on the A2A Python SDK, httpx, and uvicorn. It is licensed under MIT.

Create and run the lab

Clone the public repository and let uv create the environment from the locked dependencies:

git clone https://github.com/paladini/a2a-orchestration-lab.git
cd a2a-orchestration-lab
uv sync

Run the bundled end-to-end demo:

uv run a2a-lab demo "Explain A2A and how it relates to MCP"

The CLI starts the three agents as subprocesses, waits for their Agent Cards, sends a message to the orchestrator, prints the response, and terminates the child processes. The default prompt is the same explanation used by the repository README, but using your own prompt makes the delegation easier to recognize.

On a successful run, the output contains sections similar to these:

[demo] asking orchestrator: 'Explain A2A and how it relates to MCP'

## Orchestrator result

**User:** Explain A2A and how it relates to MCP

### Step 1 - Researcher (A2A)
# Research notes

### Step 2 - Writer (A2A)
# Brief

The exact wording is generated by the local stubs and can change with repository updates. The important result is the sequence: the orchestrator receives the prompt, delegates research, then gives the research result to the writer.

Inspect the three agents

The lab can also run each service independently. Open three terminals in the repository and start one command in each:

uv run a2a-lab run researcher
uv run a2a-lab run writer
uv run a2a-lab run orchestrator

The services listen on loopback addresses:

Orchestrator: http://127.0.0.1:9100
Researcher: http://127.0.0.1:9101
Writer: http://127.0.0.1:9102

Each exposes an Agent Card at /.well-known/agent-card.json. For example:

http://127.0.0.1:9100/.well-known/agent-card.json

An Agent Card is the discovery surface. It tells a client what an agent is, where it is available, and which skills or interfaces it advertises. In this lab, opening the cards is a practical way to connect the protocol concept to a real HTTP response.

Stop the three processes with Ctrl+C when you are finished. The one-shot demo command handles child-process cleanup in its finally block.

Follow the delegation path in the source

The most useful source-reading path is short:

Start with src/a2a_lab/cli.py. The cmd_demo function starts the agents and waits for their cards. _ask_orchestrator resolves the orchestrator card, creates an A2A client, and sends a text message.
Read the agent server and executor modules to see how a local process becomes an A2A service and how task lifecycle states are handled.
Read the orchestrator agent to see the client-side delegation to the researcher and writer.

The CLI uses the A2A Python SDK types for a SendMessageRequest, then collects the response stream into text. This is a useful separation: the CLI manages the demo lifecycle, while the agent modules implement the roles.

A2A and MCP solve different boundaries

A2A describes itself as a protocol for agent discovery and task-oriented communication. Its core concepts include messages, tasks, artifacts, Agent Cards, and task updates. In the lab, A2A is the horizontal connection between the orchestrator and its specialist agents.

MCP standardizes connections between LLM applications and external data sources or tools. Its server features include resources, prompts, and tools. MCP is therefore a natural boundary when one agent needs a capability such as filesystem access, search, or a code analysis tool.

A simple mental model is:

user -> A2A orchestrator -> A2A researcher
                       -> A2A writer
                              |
                              -> MCP tools, when a specialist needs them

The lab does not implement MCP. Its README explicitly treats MCP as a later addition after the A2A learning path. That makes the project a good place to understand agent-to-agent delegation before introducing another protocol.

What the demo proves, and what it does not

The smoke test proves that the declared Python environment resolves, the three services start, Agent Cards become reachable, a client can send a message to the orchestrator, and the pipeline returns a result. It does not prove model quality, distributed reliability, authentication, or production readiness.

The project intentionally lists several missing production concerns: portable task checkpointing, capability tokens, strong sandboxing, multi-vendor identity and trust, budgets, audit as a primitive, and governed business context. Treat that list as an implementation boundary, not as a roadmap promise.

The lab also uses loopback HTTP services and local knowledge-base stubs. Do not expose the three ports to a network and assume that localhost implies authorization. If you replace the stubs with real tools or models, add authentication, authorization, timeouts, rate limits, structured logs, and explicit data handling rules before handling sensitive input.

Failure modes and troubleshooting

If uv sync fails, verify the Python version with python --version and the tool with uv --version. The project requires Python 3.12 or newer.

If the demo reports that an agent is not ready, check whether ports 9100, 9101, or 9102 are already in use. The CLI waits up to 15 seconds for each Agent Card. Stop stale processes and try again.

If the demo prints a result but the content is unexpectedly short, remember that the researcher and writer are deterministic stubs. Change the local knowledge base or prompt to explore the flow. Adding an LLM is a separate experiment, not a prerequisite for understanding A2A.

FAQ

Does this lab require an API key?

No. The README describes the first-day workflow as local and without API keys. Its current agents use deterministic stubs.

Is A2A a replacement for MCP?

No. A2A connects agents to agents. MCP connects an AI application to tools and data sources. A system can use both, with an A2A specialist invoking MCP tools when that capability belongs inside the specialist boundary.

Does the demo run forever?

No. uv run a2a-lab demo starts the agents, runs one task, prints the result, and shuts them down. Use the separate run commands when you want to inspect services manually.

Is this ready for production?

No. The project explicitly describes itself as a learning lab and names the lifecycle, identity, capability, budget, audit, and governance gaps that remain.

Takeaway

A2A becomes easier to reason about when the first example is deterministic. The Orchestration Lab gives you three inspectable local services, discoverable Agent Cards, a real delegation path, and a clear place to add MCP later.

I used AI assistance to organize and edit this tutorial. The repository README, pyproject.toml, learning notes, CLI source, MIT license, official A2A specification, official MCP specification, and a live uv sync plus demo run were checked separately.

What would you replace first in this lab: the researcher stub, the writer stub, or the orchestrator's routing logic?

Build a Backpacking Gear List with an MCP Server

Fernando Paladini — Wed, 05 Aug 2026 12:35:51 +0000

Build a Backpacking Gear List with an MCP Server

Packing lists are easy to start and surprisingly hard to maintain. A spreadsheet can track a tent and a stove, but it does not give an AI assistant a useful interface for creating categories, updating item quantities, or generating a share link.

This tutorial shows how to run lighterpack-mcp from its public TypeScript repository and connect it to an MCP-compatible client. The server exposes LighterPack operations for lists, categories, items, weights, flags, and sharing.

TL;DR

Clone the repository, install its dependencies, build the server, and point your MCP client at the generated dist/index.js file. Provide a LighterPack username and password through environment variables, then ask the client to create a list with categories and gear.

The current GitHub repository reports version 0.1.0 in package.json, and the repository has no release tag. The public npm registry also returned 404 for lighterpack-mcp during verification on August 5, 2026, so this walkthrough deliberately uses the source checkout instead of the README's npx lighterpack-mcp example.

Prerequisites

You need:

Node.js 20 or newer.
Git.
An existing LighterPack account.
An MCP client that can launch a local stdio server.

The project is MIT licensed. It is an unofficial integration and is not affiliated with or endorsed by LighterPack.

1. Clone and verify the source

Clone the public repository and install the locked dependency tree:

git clone https://github.com/paladini/lighterpack-mcp.git
cd lighterpack-mcp
npm ci
npm test
npm run typecheck
npm run build

The repository's current scripts define npm test as the unit-test suite, npm run typecheck as a TypeScript check, and npm run build as the production compilation step. During this tutorial's verification, 75 unit tests passed, type checking passed, and the build completed successfully.

The build creates dist/index.js, which is the executable configured in package.json. Keep the checkout in a stable location because the absolute path will be part of your MCP client configuration.

2. Configure the MCP server

The server reads credentials from LIGHTERPACK_USERNAME and LIGHTERPACK_PASSWORD. It also accepts an optional LIGHTERPACK_BASE_URL, which defaults to https://lighterpack.com and can point to a self-hosted LighterPack instance.

A generic MCP configuration looks like this:

{
  "mcpServers": {
    "lighterpack": {
      "command": "node",
      "args": ["/absolute/path/to/lighterpack-mcp/dist/index.js"],
      "env": {
        "LIGHTERPACK_USERNAME": "your-username",
        "LIGHTERPACK_PASSWORD": "your-password"
      }
    }
  }
}

Replace /absolute/path/to with the checkout path on your machine. On Windows, use the path style required by your client, such as C:\\src\\lighterpack-mcp\\dist\\index.js.

Do not commit this configuration when it contains real credentials. Prefer the host's secret or environment-variable support when available, and treat the password as a credential with access to the complete LighterPack account.

3. Ask the agent to build a list

After restarting the MCP client, verify that it discovers the lighterpack server. A useful first request is intentionally small:

Use lighterpack to create a list named "Weekend Trail". Add Shelter and Kitchen categories. Add a tent weighing 1200 grams to Shelter and a stove weighing 450 grams to Kitchen. Show the resulting totals, but do not delete or overwrite any existing list.

The server's tool boundary uses grams for item weights and returns weightGrams values, even if the LighterPack interface displays another unit. The tool descriptions also expose business rules such as mutually exclusive worn and consumable flags.

Once the list looks correct, a second request can create a public read-only link:

Use lighterpack to generate a share link for "Weekend Trail". Do not change any items.

The expected result is a LighterPack list with the requested categories and items, calculated totals, and a link in the form lighterpack.com/r/<code>.

Why this works

The server is not translating each action into a granular LighterPack REST request. LighterPack stores an account's library as one JSON document. The server's SyncEngine fetches that library, clones it, applies one mutation, and saves it through POST /saveLibrary with a sync_token for optimistic concurrency.

That design explains two important behaviors:

Every write must preserve the rest of the account library. A small-looking item edit still participates in a whole-library synchronization cycle.
If another writer saves between reads, the server retries once after detecting the concurrency conflict. If you edit the same list in a browser while an agent session is active, call refresh_library before continuing.

The project keeps mutation rules in src/lighterpack/mutations.ts. Its tests cover cases such as item sharing, ID sequencing, quantity changes, star levels, the last-category guard, and worn versus consumable flags. This separation gives the MCP tools a smaller and more reviewable business-logic surface.

Failure modes and safe boundaries

The client cannot start the server

Confirm that Node.js is version 20 or newer, that npm run build created dist/index.js, and that the configured path points to that file. Run the built entry point directly to inspect startup diagnostics:

node dist/index.js

The process communicates over stdout using the MCP protocol, so diagnostics are written to stderr. Do not add ordinary logging to stdout in a local modification.

Authentication fails

Check the environment-variable names exactly. The server does not provide account registration, account deletion, password changes, email changes, or password recovery tools. Those omissions are deliberate limits on what an agent can do with the integration.

Changes appear stale

There is no realtime push channel. If the LighterPack website or another server instance changed the account, call refresh_library before making another edit. One server instance is designed for one LighterPack account.

A destructive action is requested

Treat delete_item, list deletion, category removal, and batch updates as actions requiring explicit confirmation. The README documents that delete_item cannot be undone, and some operations guard against removing the only list or category. An MCP client can expose a tool, but it cannot make an irreversible operation safe by itself.

You want a self-hosted endpoint

LIGHTERPACK_BASE_URL supports a different LighterPack endpoint, but changing it changes the trust boundary. Validate the URL before use, use HTTPS where appropriate, and understand the server's security policy before sending credentials to a non-default host.

Reproducible verification

The repository includes a network-free unit suite and an opt-in live integration suite. The unit suite can be repeated without an account:

npm test
npm run typecheck
npm run build

The live test is intentionally not part of the default test command. The contributing guide says it exercises create, edit, share, and delete against a real LighterPack account and requires RUN_INTEGRATION=1 plus real credentials. Do not enable it against an account containing data you cannot afford to change. Use a disposable account if you choose to run the live smoke test.

FAQ

Is lighterpack-mcp an official LighterPack integration?

No. The repository describes it as unofficial. It talks to the web service's own API, while the LighterPack application remains a separate project.

Can I install it with npm today?

The repository README contains an npx quick start, but the public npm registry returned 404 for lighterpack-mcp during this verification. Use the documented source checkout and build path until a published package is verifiably available.

Does it store my password in a database?

The security policy says the password is supplied through an environment variable and the authenticated session cookie is held in memory for the process lifetime. Review the code and deployment host before treating that as a complete security assessment.

Does it support multiple accounts in one server process?

No. The README documents one LighterPack account per server instance.

Takeaway

lighterpack-mcp turns a packing list into a tool interface an MCP client can understand, but the useful engineering detail is its synchronization boundary: one authenticated server instance manages one whole library document with optimistic concurrency. Build and test it locally, keep credentials outside source control, refresh before working after browser edits, and confirm destructive actions before they reach the account.

What other personal data model would benefit from a small, typed MCP layer instead of a general-purpose assistant guessing at a web UI?

AI assistance disclosure

AI assistance was used to organize this tutorial and edit its prose. The repository commands, configuration names, version details, limitations, and security boundaries were checked against the public project sources and the local verification run described above.

Give AI Coding Agents LSP Navigation with Locus MCP

Fernando Paladini — Tue, 04 Aug 2026 12:37:55 +0000

Give AI Coding Agents LSP Navigation with Locus MCP

An AI coding agent can edit a file quickly and still misunderstand the codebase. Text search finds matching strings, but it does not reliably tell you which definition is active, which callers will be affected, or what type a value has.

This tutorial shows how to connect an MCP-capable coding agent to Locus MCP, an open-source server that delegates semantic code questions to language servers. You will install the published v0.1.5 package, create project configuration, add a host entry, and verify the connection with a real prompt.

TL;DR

Install a language server, run Locus setup in the project root, and add an MCP server entry that points cwd\ at that project:

\bash npm install -g typescript-language-server typescript npx @paladini/locus-mcp init npx @paladini/locus-mcp check \\

Then configure your agent host to run npx -y @paladini/locus-mcp@0.1.5 serve\. Ask the agent to use the locate\, refs\, or hover\ tool instead of guessing from grep output.

What problem does this solve?

Suppose an agent must rename parseConfig\. Grep can list every occurrence of that text, including comments, strings, tests, generated files, and unrelated symbols. An LSP can answer a narrower question: which declaration does this identifier refer to, and which source locations reference that declaration?

Locus is a small MCP layer between the agent host and those language servers. The released documentation describes six tools:

locate\ finds a symbol or lists symbols in a file.
refs\ finds references or implementations.
hover\ returns type information and documentation.
diagnostics\ reports errors and warnings.
status\ reports language-server readiness.
rename\ previews the impact of a rename without applying edits.

The distinction matters. Locus reads code structure and diagnostics; your agent still performs edits, and grep remains useful for plain text such as logs, comments, and configuration keys. See the Locus usage guide for the supported workflow.

Prerequisites

You need:

Node.js 22 or newer.
An MCP-capable host such as Cursor, Codex, or Claude Code.
A language server installed for the language you want to inspect.
A project directory where you can create configuration files.

For a TypeScript or JavaScript project, install the TypeScript language server and compiler:

\bash npm install -g typescript-language-server typescript \\

For Python, the documented option is pip install pyright\. The getting started guide also lists gopls\ for Go and rust-analyzer\ for Rust.

Install and check Locus

Open a terminal in the root of the project you want the agent to understand. Run the published package explicitly so the example is tied to the stable v0.1.5 release:

\bash npx @paladini/locus-mcp init npx @paladini/locus-mcp check \\

init\ creates locus.toml\ and locus.json\. check\ verifies that the language-server binaries are available on PATH\. A successful TypeScript check should identify typescript-language-server\; a missing binary is a setup problem, not an MCP problem.

If your project uses more than one language, install only the servers it needs and configure the warm languages in locus.toml\:

\toml root = "." warm = ["typescript", "python"] \\

The configuration reference documents the file priority and custom server fields. Locus looks for locus.toml\, then locus.json\, then .lsp.json\ while walking up from the current directory.

Add the MCP server to your host

The host starts the server on demand. You normally do not run serve\ manually in a terminal.

For Cursor, create .cursor/mcp.json\ in the project:

\json { "mcpServers": { "locus": { "command": "npx", "args": ["-y", "@paladini/locus-mcp", "serve"], "cwd": "/absolute/path/to/your/project" } } } \\

For Codex, the equivalent project-scoped entry is TOML:

\toml [mcp_servers.locus] command = "npx" args = ["-y", "@paladini/locus-mcp", "serve"] cwd = "/absolute/path/to/your/project" \\

Replace the placeholder with the absolute project path. The cwd\ value is important because it tells Locus which codebase and configuration to inspect. After saving the file, reload MCP servers or restart the host.

The official setup walkthrough shows the corresponding Claude Code shape and the host-specific reload step.

Verify the complete path

First ask the agent to call status\:

Call the Locus MCP tool status\ and tell me which language servers are ready.

A readiness response confirms that the host can start Locus and that Locus can see the configured language server. If the response says server_starting\, wait briefly and retry. If it says server_unavailable\, run check\ again and inspect the binary path.

Then test a semantic lookup in a project with a known symbol:

Use Locus locate\ to find where UserService.authenticate\ is defined. Do not use grep.

For a refactor review, use a two-step request:

Before changing parseConfig\, use Locus to find its definition and list every reference. Show me the files and lines before editing anything.

Finally, ask for diagnostics on a changed file:

Run Locus diagnostics on src/api/handler.ts\ and report errors and warnings.

These prompts test different boundaries: server readiness, symbol resolution, reference discovery, and diagnostics. They also make the agent's intended tool visible in the conversation.

Why this works

Locus does not implement a parser for every language. It starts configured language-server processes and translates MCP tool calls into language-server requests. This lets the agent use the same general semantic services that IDEs expose, while keeping the MCP surface focused.

The configuration separates project settings from server definitions. locus.toml\ is convenient for the root and warm languages; locus.json\ can describe commands, arguments, language IDs, and file extensions. When no custom servers\ array is supplied, Locus uses its built-in defaults for TypeScript, Python, Go, and Rust.

That architecture also explains the limits. Results depend on the language server, its project configuration, its indexing state, and the files visible from the selected root. A green check\ means the executable exists on PATH\; it does not guarantee that every workspace can produce a useful answer immediately.

Failure modes and safe boundaries

If the MCP server does not appear, confirm that the host configuration is valid, cwd\ is an absolute project path, and the host was reloaded. If a language is missing, install its server and rerun check\. If indexing is still in progress, retry after server_starting\ rather than treating it as a definitive failure.

Review locus.json\ and .lsp.json\ before trusting a project. Locus runs language servers as child processes and spawns the configured command and arguments. Its security policy explicitly warns that configuration should be reviewed before use. A language server is also a separate dependency with its own security and trust boundary.

Locus does not edit code, store agent memory, replace grep, or promise complete IDE coverage. rename\ is a preview; the agent applies any actual change. For symbolic editing, persistent memory, or a much broader toolkit, the project documentation points readers to alternatives such as Serena.

FAQ

Do I need to understand LSP?

No. You need a compatible language server and the documented setup commands. Locus exposes the agent-facing MCP tools while the language server handles semantic analysis.

Do I have to install Locus globally?

No. The documented recommended path uses npx\, so the host can start the package without a global Locus installation.

Can I keep using grep?

Yes. Use Locus for symbols, references, types, and diagnostics. Use grep for strings, comments, logs, and configuration text.

What if my language is not listed?

Check whether your language server can be described in locus.json\ or .lsp.json\. The configuration reference documents custom server entries, but compatibility still depends on the language server's behavior.

Takeaway

The useful change is not adding another search command to an agent. It is giving the agent a deliberate boundary between text search and semantic code navigation. Install the language server, run init\ and check\, point the MCP host at the correct project root, and ask for status\ before relying on locate\, refs\, hover\, or diagnostics\.

This article was prepared with AI assistance. The repository, v0.1.5 package metadata, release-tagged documentation, security policy, and --help\ output were checked before publication; the article does not claim results beyond those sources and smoke checks.

What is the first code-navigation task you would delegate to an MCP server: finding definitions, reviewing references before a refactor, or checking diagnostics after an edit?

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.