Skip to content
Uvilo OS
archived Visibility internal Owner erik@uvilo.com Approver _ Created 2026-04-27 Updated 2026-04-27

Bash Refactor Plan 3

Scope: Register forge-bash in LibreChat, update FORGE.md and references, create TypeScript migration evaluation

Note: Only Forge/Configs-debian/ is in scope for config changes. Forge/Configs/ is not modified.

Spec: Bash Refactor Spec

Prior plan: Bash Refactor Plan 2

Task 1 — Register forge-bash in librechat.yaml

Spec Section 8: “forge-bash is registered in librechat.yaml…”

Add the forge-bash entry to the MCP servers section of Forge/Configs-debian/librechat.yaml:

forge-bash:
  title: "Forge Bash"
  description: "Bash execution with two-layer architecture and audit logging"
  command: node
  args:
    - /workspace/erik/uvilo-os/Forge/Configs-debian/mcp-servers/forge-bash/dist/index.js
  timeout: 330000
  initTimeout: 30000
  serverInstructions: |
    Bash execution in /workspace. Supports chains (| && || ;).
    rm is blocked — use uvilo-trash instead. All commands are audit-logged.

Keep the existing uvilo-shell entry unchanged — both coexist during validation.

Task 2 — Update FORGE.md

Spec Section 9: “All references to the removed permission system are cleaned up.”

Make these surgical edits to Forge/Configs/FORGE.md (and the debian copy at Forge/Configs-debian/FORGE.md if it differs):

  1. Remove PERMISSION RULE: Delete the entire “PERMISSION RULE” paragraph (“Never set grant values yourself…”).

  2. Remove project session workflow step 2: Delete “Check git status for uncommitted shell-permissions.yaml changes; commit if present”. Renumber subsequent steps.

  3. Replace uvilo-shell MCP server instructions with forge-bash instructions:

    Bash execution in /workspace. Supports chains (| && || ;).
rm is blocked — use uvilo-trash instead. All commands are audit-logged.

  4. Update any other references to uvilo-shell tool name (e.g., in tool schema descriptions, examples) to reference forge-bash.

Task 3 — Update /end-session Command

Spec Section 9: “/end-session command updated to remove the shell-permissions commit step.”

Read Forge/Skills/Create_Command/references/commands.md, find the /end-session entry, and remove the step that commits shell-permissions.yaml changes. Also check any referenced skill files for shell-permissions references.

Task 4 — Write TypeScript Migration Evaluation

Requirements R7: “The project must evaluate the feasibility and trade-offs of migrating all Forge MCP tools to TypeScript.”

The Research document (Section 8) already contains the full evaluation with decisions. Extract the final evaluation into a standalone document at Forge/Projects/Bash_Refactor/Bash_Refactor_TS_Migration_Evaluation.md with:

  1. Summary: Gradual migration starting with forge-bash as proof of concept. TypeScript SDK is mature, dependencies bundle cleanly, Node.js APIs cover all needed functionality. No blocking issues found.

  2. Current Python servers inventory (from Research 8.1):

    ServerLinesDependenciesComplexityMigration Effort
    uvilo-trash~290mcp, pydanticMediumLow-Medium
    typesense-mcp~160mcp, pydanticLowLow
    suprsend-mcp-proxy~80mcpLowLow

  3. SDK support: @modelcontextprotocol/server TypeScript SDK is mature. McpServer maps 1:1 to Python’s FastMCP. Zod replaces Pydantic.

  4. Per-tool migration concerns (from Research 8.1):

    • uvilo-trash: File system ops → Node.js fs.promises
    • typesense-mcp: HTTP requests → native fetch (Node 18+)
    • suprsend-mcp-proxy: Spawns binary → child_process.execFile

  5. Cost-benefit: Single language, no Python runtime, smaller Docker image, faster cold starts. Con: ~2-3 days migration effort for remaining servers.

  6. Decision: Gradual migration (Option B from Research). forge-bash validates the approach; other servers migrate one at a time after validation.

Add sidebar entry using the Update_Sidebar skill. Build to verify.

Task 5 — Update Project Research Skill

Research Section 11: “Research documents should present only the current state of findings and decisions.”

Update Forge/Skills/Project_Research/SKILL.md to replace the current rule “Research is historical/append-only — never replace existing sections” with:

No historical residue. When a recommendation changes during research, update the Finding and Recommendation sections in-place. Do not append notes about previous drafts or abandoned alternatives. Research documents are not frozen until approved — before approval, they should always reflect the current best thinking. If a decision rationale needs to be preserved, it belongs in Learnings, not in the Research document.

Add a note that the append-only rule still applies to decisions after approval (use dated revision notes), but not to findings and recommendations during research.

Task 6 — Verify No Stale References Remain

Requirements R9, Verification V9: “Grep for ‘PERMISSION REQUIRED’, ‘grant’, ‘shell-permissions’ returns no hits outside the project docs.”

Run these searches across the repo (excluding .trash/, node_modules/, dist/, and the project’s own documentation):

  1. grep -rl 'PERMISSION REQUIRED' --exclude-dir=.trash --exclude-dir=node_modules --exclude-dir=dist Forge/
  2. grep -rl 'shell-permissions' --exclude-dir=.trash --exclude-dir=node_modules --exclude-dir=dist Forge/
  3. grep -rl 'grant.*parameter' --exclude-dir=.trash --exclude-dir=node_modules --exclude-dir=dist Forge/ (context-dependent — only flag permission-related uses)

Allowed hits: files inside Forge/Projects/Bash_Refactor/ (project documentation) and Forge/Archived/Bash_Refactor/ (historical archive). All other hits must be cleaned up.

Commit all changes, build, and push.