The Problem

Parchi is an AI-powered browser copilot extension (Chrome MV3, Firefox) that enables chat-driven browser automation through a sidebar. The codebase spans 218 files with a mixed TypeScript/JavaScript frontend and backend, and exhibits structural patterns that impact maintainability and extension risk as the project grows.

What This Does

Parchi provides natural-language browser automation via a sidebar interface. The repository contains three projects: packages (100 files, 71 code files), dist-firefox (46 files, 11 code files), and types (1 file). Entry points include main in packages/relay-service/src/cli.ts:70 (reaches 28 functions), run in packages/extension/offscreen/offscreen.ts:8 (reaches 11 functions), and init in packages/extension/background/service.ts:178 (reaches 6 functions). The code touches 2 functions that read/write files, 4 that make outbound network calls, 2 that read/write a database, 1 that runs external commands, and 1 that performs cryptographic operations via crypto.randomBytes(16).toString traced from the main entry point. The packages/shared/src/index module is a hub with instability 1, importing 9 modules and imported by 0, serving as the central export point.

How It Is Wired

Execution starts at main in packages/relay-service/src/cli.ts:70, which calls log, fetchRpc, and other functions. The internal call graph has 552 resolved call edges between self-contained functions. Key hubs include packages/extension/sidepanel/ui/core/panel-ui.ts (22 importers, instability 0.15) and packages/shared/src/plan (7 importers, 0 exporters, instability 0). The most connected module is packages/extension/sidepanel/ui/core/panel-ui with 22 dependents and 4 imports. Five files are oversized (2227+ lines): packages/extension/background/service.ts, packages/extension/tools/browser-tools.ts, dist-firefox/sidepanel/panel.js, and packages/extension/sidepanel/ui/core/panel-ui.ts. Duplicated code appears across 45 files with 680 repeated 6-line blocks. The code outside itself includes database reads/writes, network calls, filesystem operations, external command execution, and crypto operations.

How To Use It

Setup: Clone via git clone https://github.com/moses-y/parchi.git (verbatim URL). Install dependencies with npm install and build with npm run build (produces dist/). For Firefox, run npm run build:firefox.

Configuration: Environment variables and keys are configured through the extension's Settings panel. The .env.example file in packages/backend/ provides reference configuration. No committed secrets were found.

Running it: The CLI entry point is packages/relay-service/src/cli.ts. Use npm run commands documented in package.json for build and test operations. The relay daemon and CLI can be invoked from the relay-service package.

Real-World Use

A user configures their AI provider (OpenAI, Anthropic, local Ollama, etc.) via the Settings panel, then uses the sidebar to navigate, read pages, click elements, and extract data through natural language prompts. The main CLI entry point can be used to manage the relay daemon for server-side operations. The packages/extension/convex/client.ts handles database operations for storing conversation state and auth tokens.

Code Health & Issues

Measured findings (32 total: 4 high, 28 medium, 0 low):

  • [MEDIUM/cognitive_load] High branching density x25 in packages/extension/ai/message-schema.ts, packages/extension/ai/message-utils.ts, packages/shared/src/json-rpc.ts (77 branch points over 224 lines). Decompose decision-heavy logic; consider table/strategy dispatch.
  • [MEDIUM/clarity] Hub module: packages/extension/sidepanel/ui/core/panel-ui.ts has 22 dependents with high-blast-radius churn. Keep stable and small; move volatile logic out.
  • [HIGH/clarity] Duplicated code blocks: 680 repeated 6-line blocks across 45 files including dist-firefox/content.js, packages/extension/content.ts, dist-firefox/sidepanel/panel.js, packages/extension/sidepanel/ui/core/panel-ui.ts. Extract shared helpers; DRY the repeated logic.
  • [HIGH/cognitive_load] Oversized file x5: packages/extension/background/service.ts, packages/extension/tools/browser-tools.ts, dist-firefox/sidepanel/panel.js. Split into cohesive units by responsibility.

Code health audit (6 findings: 0 critical, 0 high, 4 medium, 2 low):

  • [MEDIUM] Declare least-privilege permissions for GITHUB_TOKEN - .github/workflows/ci.yml declares no permissions; token inherits repository default allowing injected steps to push or mint releases.
  • [MEDIUM] Enable Dependabot or Renovate - 2 manifest(s) with no update bot configured; published advisories remain unpatched.
  • [MEDIUM] Gate pull requests on dependency vulnerability scan - no dependency scan in CI; known-vulnerable packages can reach build unchecked.
  • [MEDIUM] Set persist-credentials: false on checkout - checkout keeps token in .git/config; malicious postinstall scripts could read pushable credentials.
  • [LOW] Set timeout-minutes on workflow jobs - 1 workflow declares no job timeout; wedged steps run to six-hour platform default.
  • [LOW] Add convention files this project lacks - missing .editorconfig, .gitattributes, formatter config.

The Bottom Line

The repository delivers a functional AI browser copilot with Chrome and Firefox extensions, solid test coverage (38 test files), and CI infrastructure. However, the codebase shows significant maintainability debt: five oversized files, widespread duplication, a high-blast-radius hub module, and no dependency vulnerability scanning in CI. Teams should address the measured cognitive-load and duplication findings before adding features, and enable Dependabot plus dependency-review gating to prevent accruing technical debt. The project is viable for extension or incremental refactoring but requires attention to module boundaries and CI gatekeeping.