# BeYourself

A pattern scanner and editor for text, code, and audio. It ships with a desktop app and an MCP server, so an AI agent can drive it directly (batch-score documents, pull flagged sections, and so on) instead of only a human clicking through the UI.

Two tiers of detection for both text and code:

- **Free/instant heuristic** (`analyze_text`, `analyze_code`, etc.): lexical and regex pattern matching. Fast and free, but a weaker signal than real AI detectors. It misses well-edited output that avoids the specific patterns it looks for.
- **Deep/paid LLM judge** (`analyze_text_deep`, `analyze_code_deep`): actual semantic judgment from Claude, closer to what detectors like GPTZero or Originality.ai do, with a suggested fix for each flagged item. Costs real money and takes several seconds per call. Use it to spot-check specific files, not for batch scanning.

Both tiers give a probabilistic signal, not a certainty. Treat flags as worth a second look, not proof.

## Desktop app

```bash
npm install
npm start
```

## MCP server

```bash
npm run mcp
```

This project ships a `.mcp.json` so Claude Code finds the server automatically when working in this directory. To use it from Claude Desktop instead, add this to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "beyourself": {
      "command": "node",
      "args": ["/path/to/BeYourself/mcp-server.js"]
    }
  }
}
```

### Tools

- **analyze_text** `{ text, includeAllSentences? }`: score raw text, return flagged sentences and suggestions.
- **analyze_file** `{ path, includeAllSentences? }`: load a `.txt`, `.md`, or `.docx` file and score it.
- **batch_analyze** `{ paths[], threshold? }`: score many files at once. Returns a `needsReview` flag per file and a `needsReviewPaths` list for anything at or above the threshold (default 50).
- **get_flagged_sections** `{ path, threshold? }`: return just the sentences at or above a per-sentence score (default 25), with rewrite suggestions.
- **analyze_text_deep** `{ text, model? }`: real LLM judgment of AI likelihood, using the user's authenticated `claude` CLI, not just lexical heuristics. Costs real money per call (roughly $0.05 to $0.20 depending on prompt-cache warmth) and takes several seconds. Use it for a handful of documents that matter, not for batch scanning.
- **save_document** `{ text, outputPath }`: write edited text back out in the format `outputPath`'s extension specifies. `.docx` generates a real Word document; `.txt` and `.md` write plain text. No separate app needed to resave.
- **analyze_code** `{ code, fileName? }`: score source code for AI-typical patterns (generic names, redundant comments, boilerplate catch blocks, leftover scaffolding).
- **analyze_code_file** `{ path }`: same, loaded from disk.
- **batch_analyze_code** `{ paths[], threshold? }`: same batch/needsReview pattern as `batch_analyze`, for code.
- **analyze_code_deep** `{ code, fileName?, model? }`: real LLM code review using the `claude` CLI instead of the free regex heuristic. Catches code smells (over-engineering, non-idiomatic patterns) a regex can't, with a per-line suggested fix. Costs real money per call (roughly $0.05 to $0.20) and takes several seconds.
- **save_code_file** `{ code, outputPath }`: write edited code back to disk, preserving its extension.
- **audio_pipeline_status** `{}`: check whether Demucs, Basic Pitch, ffmpeg, FluidSynth, and the SoundFont are installed and ready.
- **run_audio_pipeline** `{ inputPath, workDir }`: separate an audio file into stems (Demucs) and transcribe each stem to MIDI (Basic Pitch), ready to load into a DAW for editing.
- **render_midi_to_audio** `{ midiPath, outputPath, soundfontPath? }`: render a single MIDI file (edited or not) back to `.wav` using FluidSynth and the bundled General MIDI SoundFont.
- **finalize_audio_track** `{ stemPaths[], outputPath, workDir, soundfontPath? }`: one-shot repackage. Renders any `.mid`/`.midi` stems back to audio, mixes with any untouched `.wav` stems, and transcodes to whatever file type `outputPath` specifies, so a track that came in as `.mp3` can go back out as `.mp3`. This is a single deterministic render, not an automated re-scan loop.
- **analyze_midi_file** `{ path }`: score a MIDI file for AI-generated or unedited composition traits: rigid quantization (notes landing exactly on-grid), flat velocity and dynamics, and exact loop-like pattern repetition. This scores the note and timing structure the pipeline already extracted via Basic Pitch. It is not an audio watermark detector. Score the freshly-transcribed MIDI, edit it, then score the edited version to see whether the edit actually changed anything.
- **batch_analyze_midi** `{ paths[] }`: score multiple MIDI files at once, for example every stem from `run_audio_pipeline`.

The audio tools need the project's `.venv` (Python 3.11, since Demucs' build chain doesn't yet support 3.13). See below.

### Example pilot workflows

> "Batch-analyze these 12 docs. For anything above 50, pull the flagged sections, rewrite them, and save back over the originals."

An agent would call `batch_analyze`, then for each path in `needsReviewPaths`: call `get_flagged_sections`, rewrite the flagged sentences, then call `save_document` with the same path.

> "Separate this track into stems and MIDI. I'll edit the MIDI in Logic. Once I'm done, repackage it as an mp3."

An agent would call `run_audio_pipeline`, wait for the user to edit the MIDI externally, then call `finalize_audio_track` with the edited MIDI paths, any untouched stems, and an `outputPath` ending in `.mp3`.

## Audio pipeline setup

Demucs' build chain doesn't yet support Python 3.13 (the system default on most current Macs), so the audio tooling lives in an isolated venv:

```bash
/opt/homebrew/bin/python3.11 -m venv .venv
./.venv/bin/pip install demucs basic-pitch "setuptools<81"
```

`setuptools<81` is needed because `resampy`, a Basic Pitch dependency, still imports the now-removed `pkg_resources` API.

`run_audio_pipeline` and `audio_pipeline_status` use `.venv/bin/demucs` and `.venv/bin/basic-pitch` if present, falling back to the global PATH otherwise.

MIDI-to-audio rendering also needs FluidSynth and a General MIDI SoundFont:

```bash
brew install fluid-synth
```

A SoundFont (`soundfonts/MuseScore_General.sf3`, MuseScore's bundled General MIDI voice set) is already included in this project.

## Tests

```bash
npm test
```

Runs the heuristic-engine sanity tests (text and code) and a real MCP client/server round-trip test covering every registered tool.

```bash
node test/audioPipeline.test.js
```

A slower integration test that runs real Demucs/Basic Pitch inference on a generated test tone. Not part of `npm test`, since it does actual model inference rather than a fast heuristic check.

## Author

Built by [will.be](https://willbe.dev).