Skip to content
BranchesTags

Repository files navigation

🤖 Tidy v1.4.5

Sovereign Personal Assistant & Office Suite with Persistent SQLite Memory & Local Stdio MCP Server

Give Google Antigravity, Claude Code, Cursor, OpenAI Codex, or Windsurf a dedicated sovereign assistant layer with zero-config persistent memory, subagent delegation, community skills discovery, Universal Skills & Agents Studio, Knowledge Harvester Studio, full B2B CRM, automated itemized invoicing, expense & cashflow telemetry, and instant SQLite FTS5 search.

npm version License: Apache-2.0 Ecosystem Compatibility RTL Native Arabic Architect Score AI Agents Compatible

English • العربية • 📚 Documentation Hub • 📖 User Manual • 🗺️ Roadmap

🌟 Overview & Platform Topology

Tidy is an autonomous personal assistant and sovereign business operations ecosystem built on top of a single local SQLite database as its permanent Single Source of Truth (SSOT). Designed to eliminate cloud lock-in, Tidy unifies cognitive memory, subagents, business pipelines, and micro-apps across your terminal, code editors, and desktop.

📦 Ecosystem Monorepo Packages & Apps

  • @tidy/core (packages/core): Pure Node 22 + node:sqlite kernel. Houses dynamic schema registration (registerSchema), WAL concurrency tuning, bilingual FTS5 BM25 search, 3-Ring Context model, Community Skills Discovery (skills-loader.js), Universal Multi-Tool Directory Scanner (multi-tool-scanner.js), Skills-LAB 15-Rule Compliance Auditor (skills-validator.js), Boilerplate Scaffolding (boilerplate-generator.js), SQLite Collections (studio.js), Knowledge Harvester (knowledge-harvester.js), Task Brief Synthesizer (brief-generator.js), subagent dispatcher, and micro-apps (Tasks, Snippets, Journal, Vault).
  • @tidy/office (packages/office): Standalone business operations pack inheriting and superseding PocketOffice. Provides B2B CRM deal pipelines (app_crm_clients), automated itemized invoicing (app_invoices), commercial proposals (app_proposals), expense tracking & cashflow P&L (app_expenses), calendar scheduler, AI Client Dossier synthesizer, and 1-click PocketOffice migration importer.
  • @tidy/cli (packages/cli): Terminal command interface (tidy binary) with interactive @clack/prompts navigation wizard.
  • @tidy/mcp (packages/mcp): Stdio JSON-RPC 2.0 Model Context Protocol server exposing 20 intelligent tools and 6 dynamic live resources.
  • @tidy/skill (packages/skill): Official TidyFactor Skills-LAB Community Skill (Apache-2.0, 15 structural rules).
  • @tidy/desktop (apps/desktop): Native Windows x64 Desktop Application (Electron + secure typed IPC + global floating HUD summoned via Alt+Space) featuring dedicated visual tabs for Universal Skills & Agents Studio, Knowledge Harvester Studio, CRM, Invoicing, and Cashflow.
  • @tidy/web (apps/web): Web Management Console running on local HTTP port 3840 with full REST API and Universal Skills & Agents Studio.

Core Capabilities

  1. Pluggable Microkernel Architecture: Pure separation of concerns between core cognitive memory (@tidy/core) and business domains (@tidy/office). Allows custom enterprise deployments (DevOps, Agencies, Developers) without engine bloat.
  2. The 3-Ring Context Architecture:
    • Ring 0 (Sovereign Profile): Permanent user preferences and assistant persona (~150 tokens).
    • Ring 1 (Domain Firewall): Context switching between dev, marketing, and personal modes without context bleed.
    • Ring 2 (Dynamic Working Memory): BM25-ranked FTS5 recall of relevant decisions, rules, and patterns.
  3. Universal Skills & Agents Studio: Native discovery across Claude Code, Cursor, Codex, Windsurf, Copilot, Antigravity/Gemini, Amp, and Aider; built-in monospaced code editor with line numbers, AST sync, and live Markdown preview; non-destructive SQLite SSOT collections & tagging; 15-rule Skills-LAB compliance auditing.
  4. Knowledge Harvester & Agent Brain Extractor: Standalone 2-Pane Master-Detail Studio for scanning, on-demand full document inspection, and atomic ingestion of knowledge items from ~/.gemini/knowledge/**, Antigravity session brain plans, and agent rules with seamless "Open in Studio" bridging.
  5. Sovereign Business Suite: Manage client pipelines, generate tax-calculated itemized invoices, record operational expenses, monitor real-time cashflow telemetry, and generate AI-powered client dossiers.
  6. Pluggable Sub-Agents & Skills Hub: Built-in core roles (planner, coder, researcher, scribe) plus dynamic integration of TidyFactor Skills-LAB community skills (@marketing, @design, @doc, @next, @php, etc.) as sovereign subagents.
  7. Self-Contained Task Brief Generator: Synthesizes autonomous task briefs combining Goal/Mission, 3-Ring Context, Skill Operational Rules, and Verification Gates.
  8. Multi-Surface Access: CLI, Stdio MCP Server, Electron Windows Desktop App (Alt+Space HUD), and Web Dashboard.

🖥️ Flagship Desktop Management Studio (@tidy/desktop)

Tidy features a first-class, sovereign desktop management suite built natively for Windows x64 using Electron. It provides an ultra-responsive visual control center directly wired into the local SQLite Single Source of Truth (~/.tidy/tidy.db), eliminating the need for terminal commands when reviewing decisions, drafting skills, or inspecting finances.

📸 Tidy Studio Visual Interface & Capabilities

1. Overview & Health Telemetry 2. Universal Skills & Agents Studio
Tidy Studio Overview Skills & Agents Studio
Real-time SQLite WAL stats, memory metrics, and quick capture Monospaced editor, AST sync, 15-rule validator, live preview
3. FTS5 BM25 Memory Explorer 4. Knowledge Harvester Studio
Memory Explorer Knowledge Harvester
Decay-scored instant search across 3-Ring context 2-Pane master-detail ingestion of agent rules & brains
5. Sovereign B2B CRM Pipeline 6. Invoicing & Live Cashflow
CRM Pipeline Invoices & Billing
Deal stages, client dossiers, and budget trackers Automated tax invoicing and real-time P&L statement

🌐 Bilingual Interface: Tidy Studio dynamically supports 8 languages with full RTL/LTR switching. The screenshots above showcase the English (LTR) interface. For the native Arabic (RTL) gallery, see دليل استوديو سطح المكتب بالعربية or browse docs/public/screenshots/desktop/ar/.

🌟 Desktop App Highlights (14 Built-in Tabs)

  1. Overview: Executive dashboard with live SQLite telemetry, system health, and quick-action memory capture.
  2. Skills & Agents Studio: Built-in IDE scanner, code editor with syntax tree synchronization, and Skills-LAB 15-rule compliance engine.
  3. Memory Explorer: Visual FTS5 BM25 search interface with mathematical decay indicators and importance star filters.
  4. Knowledge Harvester: Dual-pane browser to scan, preview, and ingest knowledge items from ~/.gemini/ and IDE sessions.
  5. Agent Runner: Autonomous subagent dispatcher (@coder, @planner, @marketing, @doc) with 3-Ring Task Brief generation.
  6. MCP Studio: Complete visual catalog of all 29 MCP tools and 9 dynamic resources with JSON-RPC tester.
  7. Task Kanban Board: Organize pending, in-progress, and completed tasks with subagent assignment.
  8. Code Snippets Vault: Monospaced syntax-highlighted code vault with one-click copy.
  9. Daily Journal: Private developer reflection and continuous session logging.
  10. Encrypted Vault: High-security local credential store with zero cloud transmission.
  11. B2B CRM: Lead pipelines, client records, and proposal budgets.
  12. Invoicing & Billing: Multi-item tax invoices with payment status toggles.
  13. Cashflow Statement: Automated P&L financial statements with real-time margins.
  14. Settings & Health: SQLite database compaction (VACUUM), WAL checkpoints, and domain switching.

⚡ Global Floating HUD (Alt + Space)

Summon Tidy anywhere in Windows with Alt + Space. The frameless HUD provides rapid memory search, quick fact capture, and task generation without switching windows or interrupting your coding flow.

# Launch Desktop Studio in Development
npm run desktop

# Build Windows x64 Native Installer (.exe)
npm run desktop:build

🛠️ Quick Start & Usage

💡 For the comprehensive command reference and end-to-end workflows, see the 📖 User Manual.

1. Interactive Terminal Wizard (Recommended)

Launch the modern, interactive @clack/prompts navigation interface:

tidy
# or explicitly:
tidy ui

2. Fast Developer One-Liners & Cognitive Memory

High-speed terminal commands for daily coding and agent collaboration:

# Instant memory search with mathematical decay & stars ranking
tidy q "WAL mode"
tidy q "auth" --bypass   # Bypass domain firewall for global search

# Instant memory capture in 1 second
tidy m "Use WAL mode for high concurrency" --cat decision --imp 5

# Quick task management with autonomous memory feedback loop
tidy task "Implement OAuth2" --priority urgent --domain dev --agent coder
tidy tasks --pending
tidy done tsk_xxx --result "Implemented with JWT verification"  # Auto-archives decision to memory!

# Autonomous Subagent & Skill Runner (3-Ring Context Injection)
tidy run coder "Audit SQLite indexes and foreign keys"
tidy run marketing "Draft product launch post for Twitter"
tidy run doc "Generate API references for MCP endpoints"

# Instant diagnostics, search, and storage hygiene
tidy doc                    # Full SQLite, WAL & knowledge base health check
tidy search "FTS5 BM25"     # Hybrid recall across SQLite DB & disk markdown files
tidy clean                  # Storage audit with dry-run inspection of recordings & caches
tidy firewall "New ad copy" # Instant check against domain bleed

# Quick status & firewall inspection
tidy who
tidy whoami

3. CRM & Client Pipeline

# List active clients
node bin/tidy.js crm list

# Add a new client
node bin/tidy.js crm add --name "Acme Corp" --budget 15000 --status prospect

4. Invoicing & Billing Engine

# List all invoices
node bin/tidy.js invoice list

# Create itemized invoice with 15% tax
node bin/tidy.js invoice create --client cli_xxxx --tax 15 --items '[{"name":"Backend API Migration","qty":1,"unitPrice":4500}]'

# Mark invoice as paid
node bin/tidy.js invoice pay inv_xxxx

5. Expenses & Live Cashflow Telemetry

# Record operational expense
node bin/tidy.js expense add --title "Cloud Server Hosting" --amount 240 --category hosting

# Audit live cashflow statement (Revenue, Expenses, Net Profit, Margin, Receivables)
node bin/tidy.js cashflow

6. AI Client Dossier Synthesizer

# Compile instant executive dossier combining CRM, Invoices, Proposals, and FTS5 Memory
node bin/tidy.js dossier cli_xxxx

7. PocketOffice 1-Click Migration

# Import existing PocketOffice data into Tidy SQLite SSOT
node bin/tidy.js import-pocketoffice --source ./path/to/PocketOffice-Data

8. Save & Recall Memories

# Save an architectural decision
node bin/tidy.js memory save "Project uses Next.js 16 and Supabase with strict tenant isolation"

# Instant BM25 search
node bin/tidy.js memory recall "Next.js"

9. Switch Contexts & Domains

node bin/tidy.js context list
node bin/tidy.js context switch ctx_dev

10. Delegate to Subagents & Synthesize Briefs

node bin/tidy.js agent run coder "Review database schema performance"
node bin/tidy.js brief "Build cashflow analytics dashboard"

🔌 Stdio MCP Server Configuration

Add to your IDE MCP configuration (mcp_config.json):

{
  "mcpServers": {
    "tidy": {
      "command": "node",
      "args": ["packages/mcp/src/server.js"]
    }
  }
}

Registered Tools (29 Tools)

  • Cognitive & Working Memory: tidy_recall, tidy_memorize, tidy_get_context, tidy_switch_context, tidy_whoami.
  • Sovereign Brain & Forensic Diagnostics: tidy_doctor, tidy_search, tidy_extract, tidy_transcripts, tidy_hygiene, tidy_firewall, tidy_manifest.
  • Knowledge Harvester & Brain Extraction: tidy_harvest_scan, tidy_harvest_read, tidy_harvest_import.
  • Governance & Configuration: tidy_config_get, tidy_config_set, tidy_profile_update, tidy_govern_rules.
  • Tasks & Autonomous Subagents: tidy_task_add, tidy_task_list, tidy_exec_subagent, tidy_list_skills, tidy_synthesize_brief.
  • Database Telemetry: tidy_db_stats.
  • Office Suite (@tidy/office):
    • tidy_crm_list: List CRM clients, deal pipelines, and budgets.
    • tidy_crm_add: Register a new B2B client.
    • tidy_invoice_list: Query invoices by status, client, or due date.
    • tidy_invoice_create: Generate itemized invoices with automated tax and discounts.
    • tidy_cashflow_summary: Live P&L financial statement.
    • tidy_client_dossier: Comprehensive AI client dossier fusing financial ledger and institutional memory.

Dynamic Live Resources (9 Resources)

  • tidy://profile: Sovereign user profile and operating tone.
  • tidy://context/current: Active project context and domain firewall constraints.
  • tidy://tasks/pending: Pending tasks queue.
  • tidy://brain/doctor: Live system diagnostic health report.
  • tidy://brain/taxonomy: 4-tier knowledge base taxonomy and index.
  • tidy://brain/hygiene: Disk storage breakdown and cleanup candidates.
  • tidy://office/cashflow: Real-time financial cashflow statement.
  • tidy://config: System configuration provider snapshot.
  • tidy://govern: Active contextual governance and firewall policies.

Model Context Protocol (MCP) Prompts

  • task_brief: Synthesize autonomous 3-Ring Task Briefs with operational guidelines.
  • extract_ki: Atomic Knowledge Item (KI) creator enforcing negative constraints.
  • firewall_audit: Contextual domain firewall audit guide.
  • agent / run: Instant autonomous subagent runner with 3-Ring context injection.

Zero-Breakage Legacy Aliases

Seamless backward compatibility for legacy IDE configs with automatic argument normalization (doctor, probe_server_health, recall_memory, search_knowledge_base, extract_knowledge_item, contextual_firewall, get_skill_manifest, whoami).

Remote Web MCP Server (HTTP JSON-RPC 2.0)

Connect IDE agents remotely via POST http://localhost:3840/mcp with complete tool execution, resource subscriptions, and prompts support without local CLI overhead.

🏛️ Architecture & Governance

Tidy adheres strictly to the 15 Structural Rules of TidyFactor Skills:

  • Dispatcher Discipline: SKILL.md is a clean router (~350 tokens) with explicit anti-triggers.
  • Contextual Decision Layer (CDL v2.0): Automatic Context Delta Resolution before prompting.
  • Operational Memory Isolation: Clean separation between pure technical schemas and human documentation.
  • Pluggable Microkernel: Core engine remains clean, fast, and unpolluted by domain-specific business rules.

📚 Documentation & Ecosystem Guides

The Tidy repository is organized around a single root README.md and a modular Documentation Hub:

Guide / Specification Scope & Description Link
Documentation Hub Master index of all project guides, specs, and translations docs/README.md
User Manual (العربية) Comprehensive operating manual for CLI, MCP, HUD & Apps docs/user_manual.ar.md
Project Status & SemVer Active component status & SemVer roadmap (v1.4.3 – v2.0.0) docs/PROJECT_STATUS.ar.md
System Architecture Technical specification of SQLite WAL, FTS5 & Context Rings ARCHITECTURE.md
Product Roadmap Strategic multi-phase product roadmap and release plan ROADMAP.md
AI Agent Guidelines Autonomous coding agent operating contract & invariants AGENTS.md
Skill Manifest TidyFactor Skills-LAB certified skill router packages/skill/SKILL.md
Release Changelog Complete historical SemVer changelog CHANGELOG.md
Security Policy Zero-telemetry guarantee & private vulnerability reporting SECURITY.md
Contributing Guide Development workflows, test suites, and contribution rules CONTRIBUTING.md

⚡ Interactive Documentation Portal (VitePress)

Run the local interactive documentation portal with instant search and full RTL/LTR support:

npm run docs:dev    # Start live development server
npm run docs:build  # Compile static production bundle (SSG)

🌐 International Translations (docs/i18n/)

⚖️ License

Apache-2.0 © 2026 TidyFactor Team. See LICENSE for terms.

About

Sovereign Personal Assistant & Memory OS with SQLite SSOT, local MCP server, and multi-agent studio

tidyfactor.com/tidy

Topics

agent-memoryagent-skillagent-skillsagentic-aiai-agentantigravityclaude-codelocal-firstlocal-first-aimcpmcp-servermemory-osmodel-context-protocolnodejspersonal-assistantprivacy-first-aisovereignsqlitetidyfactor

Resources

Readme
License

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages