docs: update dev setup + architecture docs for v1.64.0 fold#334
Open
Akarsh-Hegde wants to merge 2 commits into
Open
docs: update dev setup + architecture docs for v1.64.0 fold#334Akarsh-Hegde wants to merge 2 commits into
Akarsh-Hegde wants to merge 2 commits into
Conversation
v1.64.0 shipped the fold: dashboard is now a static export embedded in the Tauri binary, capture runs in-process (no separate screenpipe/a11y- helper), and the Tauri tray owns the full dev surface. All docs and dev scripts were still describing the old multi-process topology. Changes: - dev-start.sh: remove stale screenpipe launchd bootstrap and the redundant Next.js Terminal window — `npm run tauri dev` starts the Next.js dev server automatically via beforeDevCommand. Now 3 windows (daemon, MLX, tray) instead of 4. - install-dev.sh: remove screenpipe + a11y-helper launchd registration (capture is in-process; those agents conflict and are unneeded). Add migration note for devs with an older setup. - CONTRIBUTING.md: update project layout (add meridian-core), dev setup table (3 windows, no screenpipe), installed-vs-dev table, TypeScript convention (bridge.ts invoke pattern, no /api routes). - tray/README.md: full rewrite — previous version described HTTP polling of /api routes and curl http://localhost:3939 checks, both retired at the fold. Now documents the actual architecture (in-process capture, embedded dashboard, poll loop, Tauri commands, MLX supervision). - README.md: update "Built on" section — screenpipe is now a forked capture crate, not a separate process; add Tauri. - SETUP.md: grant permissions to Meridian (not screenpipe); update services table (remove screenpipe row); update log targets; add MLX runtime download step to setup flow. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SKdh3tKWLZhtQ9FCfA5RYH
Add 5 regression tests to tray_assets.rs that lock the fold's dev-setup changes so a future edit can't silently revert the topology: - dev_start_no_screenpipe_launchd_bootstrap: dev-start.sh must not bootstrap a screenpipe launchd agent (capture is in-process) - dev_start_no_separate_nextjs_window: dev-start.sh must not open a separate `npm run dev` window (tauri dev handles it via beforeDevCommand) - dev_start_opens_three_terminal_windows: exactly 3 `do script` calls (daemon, MLX, tray) — not 4 - install_dev_skips_screenpipe_agents: install-dev.sh must not call install-screenpipe-daemon.sh or install-a11y-helper-daemon.sh - tauri_before_dev_command_starts_nextjs: tauri.conf.json must keep the beforeDevCommand that auto-starts the Next.js dev server Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SKdh3tKWLZhtQ9FCfA5RYH
📝 WalkthroughWalkthroughThe PR updates the local development workflow from 4 terminal windows to 3 by removing the separate Next.js terminal (Tauri's ChangesDev topology: 3-terminal workflow and in-process capture
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@CONTRIBUTING.md`:
- Around line 53-57: The blockquote in the upgrade note violates markdownlint
MD031 because the fenced code block is not separated by blank quote lines.
Update the markdown in the “Upgrading from an older dev setup?” section so the
quoted fenced block in CONTRIBUTING.md has an empty blockquote line before and
after the fence, keeping the quote formatting intact around the launchctl
example.
In `@tests/tray_assets.rs`:
- Around line 155-248: The Rust file header in tests/tray_assets.rs is missing
the required leading space in the top comment, so update the file start to match
the standard `// ambient...` convention. Fix the opening comment at the top of
the file and ensure the header formatting remains consistent with other Rust
test files in this module.
In `@tray/README.md`:
- Line 9: The README has markdownlint issues in fenced blocks: the top diagram
fence in the tray overview needs a language tag, and the fenced block under the
tray logs section needs a blank line before it. Update the markdown in
tray/README.md so the diagram fence is labeled with a suitable language such as
text, and add the missing spacing before the bash fence; use the surrounding
README sections and the fenced block markers as the key locations to adjust.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: ca5a01e2-9ddf-48da-80e2-c9d570eaf01e
📒 Files selected for processing (7)
CONTRIBUTING.mdREADME.mdSETUP.mddev-start.shinstall-dev.shtests/tray_assets.rstray/README.md
📜 Review details
⏰ Context from checks skipped due to timeout. (2)
- GitHub Check: Rust
- GitHub Check: Analyze (rust)
🧰 Additional context used
📓 Path-based instructions (1)
**/*.{rs,ts,tsx}
📄 CodeRabbit inference engine (CLAUDE.md)
Every Rust, TypeScript, and TSX file must start with the required ambient dev tool comment as its first line.
Files:
tests/tray_assets.rs
🪛 markdownlint-cli2 (0.22.1)
tray/README.md
[warning] 9-9: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 82-82: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
CONTRIBUTING.md
[warning] 54-54: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
Comment on lines
+53
to
+57
| > **Upgrading from an older dev setup?** If you have screenpipe or a11y-helper registered from before v1.64.0, remove them: | ||
| > ```bash | ||
| > launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.meridiona.screenpipe.plist | ||
| > launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.meridiona.a11y-helper.plist | ||
| > ``` |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Fix markdownlint MD031 around the fenced blockquote code block.
Line 54’s fenced block should be surrounded by blank lines inside the blockquote.
Proposed fix
> **Upgrading from an older dev setup?** If you have screenpipe or a11y-helper registered from before v1.64.0, remove them:
+>
> ```bash
> launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.meridiona.screenpipe.plist
> launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.meridiona.a11y-helper.plist
> ```
+>📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| > **Upgrading from an older dev setup?** If you have screenpipe or a11y-helper registered from before v1.64.0, remove them: | |
| > ```bash | |
| > launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.meridiona.screenpipe.plist | |
| > launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.meridiona.a11y-helper.plist | |
| > ``` | |
| > **Upgrading from an older dev setup?** If you have screenpipe or a11y-helper registered from before v1.64.0, remove them: | |
| > | |
| > |
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 54-54: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@CONTRIBUTING.md` around lines 53 - 57, The blockquote in the upgrade note
violates markdownlint MD031 because the fenced code block is not separated by
blank quote lines. Update the markdown in the “Upgrading from an older dev
setup?” section so the quoted fenced block in CONTRIBUTING.md has an empty
blockquote line before and after the fence, keeping the quote formatting intact
around the launchctl example.
Source: Linters/SAST tools
Comment on lines
+155
to
+248
| // ── Dev-setup contract guards (v1.64.0 fold) ────────────────────────────── | ||
| // These lock invariants of the dev-script changes that landed with the fold. | ||
| // A future edit that accidentally reverts the topology (re-adding a separate | ||
| // Next.js window, re-enabling screenpipe agents) should break `cargo test` | ||
| // rather than silently breaking new-contributor setup. | ||
|
|
||
| /// GUARD: `dev-start.sh` must no longer bootstrap screenpipe as a launchd | ||
| /// agent. v1.64.0 runs capture in-process inside the Tauri tray binary — a | ||
| /// screenpipe launchd agent conflicts and is unneeded. The old 80-line block | ||
| /// (`Ensure screenpipe is up`) was removed; this assertion prevents it from | ||
| /// creeping back. | ||
| #[test] | ||
| fn dev_start_no_screenpipe_launchd_bootstrap() { | ||
| let src = read_text("dev-start.sh"); | ||
| assert!( | ||
| !src.contains("LABEL_SCREENPIPE"), | ||
| "dev-start.sh must not bootstrap a screenpipe launchd agent \ | ||
| (capture is in-process inside the Tauri tray since v1.64.0). \ | ||
| Remove the LABEL_SCREENPIPE / launchctl bootstrap block." | ||
| ); | ||
| assert!( | ||
| !src.contains("install-screenpipe-daemon.sh"), | ||
| "dev-start.sh must not call install-screenpipe-daemon.sh" | ||
| ); | ||
| } | ||
|
|
||
| /// GUARD: `dev-start.sh` must not open a separate Next.js terminal window. | ||
| /// `npm run tauri dev` starts the Next.js dev server automatically via | ||
| /// `beforeDevCommand` in `tauri.conf.json` — a second window runs it twice. | ||
| /// The fold removed window 3 ("Next.js UI"); this prevents it returning. | ||
| #[test] | ||
| fn dev_start_no_separate_nextjs_window() { | ||
| let src = read_text("dev-start.sh"); | ||
| assert!( | ||
| !src.contains("npm run dev"), | ||
| "dev-start.sh must not start a separate `npm run dev` window — \ | ||
| `npm run tauri dev` handles this via beforeDevCommand. \ | ||
| Running both starts two Next.js processes on the same port." | ||
| ); | ||
| } | ||
|
|
||
| /// GUARD: `dev-start.sh` must open exactly 3 Terminal windows (daemon, MLX, | ||
| /// tray). The old 4-window setup had a redundant Next.js window; the new fold | ||
| /// topology has 3. Counts `do script` calls in the embedded AppleScript block. | ||
| #[test] | ||
| fn dev_start_opens_three_terminal_windows() { | ||
| let src = read_text("dev-start.sh"); | ||
| let count = src.matches("do script \"").count(); | ||
| assert_eq!( | ||
| count, 3, | ||
| "dev-start.sh must open exactly 3 Terminal windows (daemon, MLX, tray). \ | ||
| Found {count} `do script` calls. If you added a new service window, \ | ||
| update this test to reflect the new expected count." | ||
| ); | ||
| } | ||
|
|
||
| /// GUARD: `install-dev.sh` must not register screenpipe or a11y-helper as | ||
| /// launchd agents. Both are unneeded since v1.64.0 (capture is in-process); | ||
| /// registering them causes a duplicate-capture conflict. | ||
| #[test] | ||
| fn install_dev_skips_screenpipe_agents() { | ||
| let src = read_text("install-dev.sh"); | ||
| assert!( | ||
| !src.contains("install-screenpipe-daemon.sh"), | ||
| "install-dev.sh must not call install-screenpipe-daemon.sh \ | ||
| (screenpipe is no longer a separate process — capture is in-process \ | ||
| inside the Tauri tray since v1.64.0)." | ||
| ); | ||
| assert!( | ||
| !src.contains("install-a11y-helper-daemon.sh"), | ||
| "install-dev.sh must not call install-a11y-helper-daemon.sh \ | ||
| (a11y capture is in-process inside the Tauri tray since v1.64.0)." | ||
| ); | ||
| } | ||
|
|
||
| /// GUARD: `tauri.conf.json`'s `beforeDevCommand` must start the Next.js dev | ||
| /// server. This is what removes the need for a separate Next.js terminal in | ||
| /// `dev-start.sh` — if the beforeDevCommand is removed or changed, the | ||
| /// dashboard would be blank in dev mode without an explicit `npm run dev`. | ||
| #[test] | ||
| fn tauri_before_dev_command_starts_nextjs() { | ||
| let conf = read_json(CONF); | ||
| let before_dev = conf["build"]["beforeDevCommand"] | ||
| .as_str() | ||
| .unwrap_or_default(); | ||
| assert!( | ||
| before_dev.contains("npm run dev"), | ||
| "tauri.conf.json build.beforeDevCommand must start the Next.js dev \ | ||
| server (contain `npm run dev`). Without it, `npm run tauri dev` opens \ | ||
| a blank webview and a separate Next.js terminal is needed again. \ | ||
| Found: {before_dev:?}" | ||
| ); | ||
| } | ||
|
|
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
file="tests/tray_assets.rs"
required='// ambient dev tool that watches what you do and updates your PM tickets automatically, boosting developer productivity'
first_line="$(head -n 1 "$file")"
printf 'First line in %s:\n%s\n' "$file" "$first_line"
if [[ "$first_line" != "$required" ]]; then
echo "Header mismatch."
exit 1
fi
echo "Header matches required ambient comment."Repository: Meridiona/meridian
Length of output: 328
Fix the Rust file header in tests/tray_assets.rs
Line 1 starts with //ambient... instead of the required // ambient... header, so the file does not match the Rust file-start convention.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@tests/tray_assets.rs` around lines 155 - 248, The Rust file header in
tests/tray_assets.rs is missing the required leading space in the top comment,
so update the file start to match the standard `// ambient...` convention. Fix
the opening comment at the top of the file and ensure the header formatting
remains consistent with other Rust test files in this module.
Source: Coding guidelines
| - **Launchd integration**: Registered as `com.meridiona.tray` to auto-start on login | ||
| The tray is the central process — it replaces the old Node UI server and the external screenpipe process: | ||
|
|
||
| ``` |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Address markdownlint failures in fenced code blocks.
At Line 9, add a language to the fence (e.g., text).
At Line 82, add a blank line before the fenced block.
Proposed fix
-```
+```text
Tauri tray binary
├── In-process capture (screenpipe-screen + screenpipe-a11y)
│ └── writes capture_frames / capture_ui_events → meridian.db
├── Embedded dashboard (static Next.js export in ui/out/)
@@
**Tray icon not appearing / app won't launch**
+
```bash
# View tray logs
tail -f ~/.meridian/logs/tray.logAlso applies to: 81-83
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 9-9: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@tray/README.md` at line 9, The README has markdownlint issues in fenced
blocks: the top diagram fence in the tray overview needs a language tag, and the
fenced block under the tray logs section needs a blank line before it. Update
the markdown in tray/README.md so the diagram fence is labeled with a suitable
language such as text, and add the missing spacing before the bash fence; use
the surrounding README sections and the fenced block markers as the key
locations to adjust.
Source: Linters/SAST tools
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
v1.64.0 shipped the fold to main, but all developer-facing docs and dev scripts still described the old multi-process topology (screenpipe agent, Node UI server, 4-terminal dev setup). This PR brings them up to date so a new contributor following CONTRIBUTING.md gets a working environment on the first try.
What changed
dev-start.sh— 85 lines → 3 windowsnpm run tauri devstarts the Next.js dev server automatically viabeforeDevCommandintauri.conf.json; opening a secondnpm run devran two servers on port 3939install-dev.shinstall-screenpipe-daemon.shandinstall-a11y-helper-daemon.shregistration (both are stale since v1.64.0 in-process capture)bootoutthe old agents)CONTRIBUTING.mdmeridian-core/, updatedui/andtray/descriptionstauri dev↔beforeDevCommandconnection; added the popover known limitation/apiroutes are gone)tray/README.md— complete rewrite/api/health,/api/active,curl http://127.0.0.1:3939checks — all retired at the foldREADME.mdSETUP.mdscreenpipe/screenpipe-error, addedtray/tray-errorTests
5 new regression guards added to
tests/tray_assets.rs(all pass):dev_start_no_screenpipe_launchd_bootstrapdev_start_no_separate_nextjs_windownpm run devwindow being re-added (double-starts the dev server)dev_start_opens_three_terminal_windowsinstall_dev_skips_screenpipe_agentstauri_before_dev_command_starts_nextjsbeforeDevCommandbeing removed fromtauri.conf.json(would break devURL without an explicit Next.js terminal)Test plan
bash install-dev.shon a clean machine produces no screenpipe/a11y-helper agentsbash dev-start.shopens exactly 3 Terminal windows; dashboard loads in the Tauri webviewcargo test --test tray_assets— all 11 tests pass ✅ (pre-push verified)🤖 Generated with Claude Code
https://claude.ai/code/session_01SKdh3tKWLZhtQ9FCfA5RYH
Summary by CodeRabbit
Documentation
Tests