English · 简体中文
Important
LunaScope has been completely rebuilt. Version 0.5.0 replaces the previous implementation rather than incrementally updating it. Please download the latest release and do not use an older build.
LunaScope is a Windows-first, local AI agent workbench for real repository work and course-centered learning. It combines a task-adaptive agent graph, isolated Git worktrees, typed collaboration, an append-only event model, independent verification, Skills and MCP integration, and UltraNote course projects in a compact Tauri desktop application.
Download LunaScope 0.5.0 · Release notes · Architecture notes · UltraNote audit
LunaScope is designed around one boundary: a model may propose work, but only narrow tools, explicit policy, isolated filesystems, persisted evidence, and an independent verifier are allowed to turn that proposal into workspace changes.
- Desktop, not a browser shell — a compact custom title bar, project switcher, conversation list, course context, run controls, and native dialogs form one Windows application.
- Adaptive orchestration — the planner creates the smallest useful directed acyclic graph (DAG), with explicit dependencies, acceptance criteria, write scopes, tools, risks, and evidence requirements.
- Parallel execution without shared checkouts — workers become ready from dependency completion and run in isolated Git worktrees.
- Structured communication — handoffs, shared knowledge, dependency evidence, context receipts, and recipient-specific information needs are typed and persisted.
- Evidence before delivery — changes are integrated in a separate worktree, checked by an independent verifier, and written back only after acceptance criteria pass.
- Course-aware UltraNote projects — course metadata and source documents form a shared project foundation while every conversation keeps independent history.
- Local ownership — project files remain in user-selected workspaces, model credentials use Windows Credential Manager, and application state is stored locally.
mindmap
root((LunaScope 0.5.0))
Desktop application
Tauri 2 host
Vanilla TypeScript UI
Native project switcher
Custom Windows title bar
Companion window
Agent orchestration
Task adaptive DAG
Typed worker contracts
Readiness scheduler
Isolated Git worktrees
Integration worktree
Independent verifier
Atomic write through
Collaboration
Dependency exact context
Recipient aware messages
Typed handoffs
Shared knowledge records
Context budgets and receipts
Provenance and evidence
UltraNote
Course code and name
Optional description
Multi document import
Course manifest
Managed AGENTS context
Classroom Skills
Reading and generation tools
Independent conversations
Persistence
Append only events
SQLite WAL
Materialized projections
Restart recovery
Usage records
Providers and extensions
OpenAI compatible
DeepSeek compatible
Anthropic compatible
Relay endpoints
Skills
MCP servers
Safety
Typed Tauri commands
Path confinement
Permission policy
Approval gates
Bounded inputs
Hash verified patches
flowchart TB
subgraph UI[Desktop presentation]
TS[Vanilla TypeScript views]
STORE[Frontend projection store]
MAIN[Main desktop window]
COMP[Isolated companion window]
end
subgraph HOST[Tauri desktop host]
CMD[Typed commands]
ORCH[Application orchestration]
PROJECT[Project and UltraNote setup]
PATHS[Data path manager]
end
subgraph RUNTIME[Agent runtime]
PLAN[Planner and worker materializer]
SCHED[Readiness scheduler]
CONTEXT[Context builder]
TOOLS[Typed tool router]
WORKTREE[Worktree manager]
VERIFY[Integration and verification]
DOCS[Document engine]
SKILLS[Skills and MCP loader]
end
subgraph SERVICES[Core services]
PROVIDER[Provider transport]
DB[SQLite event store]
CORE[Domain types and projections]
KEYCHAIN[Windows Credential Manager]
end
TS --> STORE
MAIN --> TS
COMP --> CMD
STORE <-->|Tauri IPC and events| CMD
CMD --> ORCH
CMD --> PROJECT
CMD --> PATHS
ORCH --> PLAN
PLAN --> SCHED
SCHED --> CONTEXT
CONTEXT --> SKILLS
SCHED --> TOOLS
TOOLS --> WORKTREE
TOOLS --> DOCS
SCHED --> VERIFY
ORCH --> PROVIDER
ORCH --> DB
PROJECT --> DB
DB --> CORE
PROVIDER --> CORE
PROVIDER --> KEYCHAIN
Dependency direction is intentionally narrow: lunascope-core knows nothing about the database, network, desktop, or operating system. The runtime composes core contracts with the store and provider. Tauri commands are adapters, and the UI consumes projections rather than becoming an authoritative state store.
flowchart LR
GOAL[User objective] --> RUN[Create persisted run]
RUN --> PLAN[Model creates task adaptive DAG]
PLAN --> VALIDATE{Validate contracts and dependencies}
VALIDATE -->|invalid| FALLBACK[Bounded fallback or actionable failure]
VALIDATE -->|valid| READY[Readiness scheduler]
READY --> W1[Worker A isolated worktree]
READY --> W2[Worker B isolated worktree]
W1 --> H1[Typed handoff and patch evidence]
W2 --> H2[Typed handoff and patch evidence]
H1 --> NEXT[Dependency ready worker]
H2 --> NEXT
NEXT --> INTEGRATE[Integration worktree]
INTEGRATE --> VERIFY[Independent verifier]
VERIFY -->|all criteria pass| APPLY[Atomic workspace write through]
VERIFY -->|repairable| ADJUST[Bounded plan patch or retry]
ADJUST --> READY
VERIFY -->|needs authority| INTERVENE[User intervention]
RUN -. append events .-> LOG[(Event log)]
PLAN -. append events .-> LOG
READY -. append events .-> LOG
W1 -. tools and evidence .-> LOG
W2 -. tools and evidence .-> LOG
VERIFY -. verdict .-> LOG
Every worker contract contains observable acceptance criteria, expected artifacts, evidence requirements, permitted tools, read/write scopes, dependencies, risk, and context visibility. A worker starts when its own dependencies complete; unrelated branches do not wait at a global level barrier.
Workers never share a checkout. A clean repository uses dependency-exact worktrees. A dirty or non-Git workspace is represented by a bounded live shadow repository so that uncommitted files—including newly imported UltraNote sources—remain visible without copying runtime caches.
flowchart TB
subgraph PRODUCER[Producer worker]
WORK[Perform scoped work]
RESULT[Patch plus evidence]
HANDOFF[Typed handoff]
end
subgraph KNOWLEDGE[Persisted collaboration state]
BOARD[Shared knowledge records]
EDGE[Recipient specific edge payload]
RECEIPT[Context receipt]
EVENTS[(Append only events)]
end
subgraph CONSUMER[Downstream worker]
NEEDS[Declared information needs]
BUDGET[Prioritized context budget]
ACTION[Scoped execution]
USE[Usage feedback]
end
WORK --> RESULT --> HANDOFF
HANDOFF --> BOARD
HANDOFF --> EDGE
NEEDS --> EDGE
BOARD --> BUDGET
EDGE --> BUDGET
BUDGET --> RECEIPT --> ACTION --> USE
HANDOFF --> EVENTS
RECEIPT --> EVENTS
USE --> EVENTS
Context is dependency-aware instead of transcript-wide. Builders normally receive their upstream patch closure, relevant artifacts, course/project instructions, and direct consumer needs. Reviewers can receive broader plan visibility. Unrelated private reasoning and unrelated conversation history are not broadcast.
The runtime records exact context visibility and evidence provenance. Handoffs describe completed work, changed paths, checks, decisions, risks, unresolved questions, artifacts, and evidence. This makes collaboration replayable and inspectable rather than hidden in free-form chat.
UltraNote is a project type, not a separate note panel. It binds course identity, source material, Skills, document tools, and independent conversations to the same workspace.
flowchart TB
CREATE[Create project] --> KIND{Project type}
KIND -->|General| GENERAL[General agent workspace]
KIND -->|UltraNote| FORM[Course code and name required<br/>description optional]
FORM --> IMPORT[Import up to 12 course files<br/>64 MiB per source]
IMPORT --> MANIFEST[.ultranote/course.json]
IMPORT --> SOURCES[.ultranote/sources]
FORM --> AGENTS[Managed course block in AGENTS.md]
MANIFEST --> FOUNDATION[Shared course foundation]
SOURCES --> FOUNDATION
AGENTS --> FOUNDATION
FOUNDATION --> T1[Conversation A<br/>independent history]
FOUNDATION --> T2[Conversation B<br/>independent history]
FOUNDATION --> T3[Conversation C<br/>independent history]
T1 --> READ[Read and understand sources]
T2 --> STUDY[Study design and retrieval practice]
T3 --> AUTHOR[Create class materials]
READ --> CITE[Page and slide aware evidence]
STUDY --> QUIZ[Plans, quizzes, explanations]
AUTHOR --> OUTPUT[Markdown, DOCX, PPTX, PDF]
course-workspace/
├─ AGENTS.md Human-readable managed course context
└─ .ultranote/
├─ course.json Authoritative metadata and source manifest
└─ sources/
├─ <uuid>-syllabus.pdf
├─ <uuid>-lecture-01.pptx
└─ <uuid>-reading.docx
- Course code and course name are required; description is optional.
- Imported source records contain a safe relative path, media type, byte size, and SHA-256 digest.
- The managed
AGENTS.mdblock is updated without overwriting user-authored content outside the markers. - Supported imports: PDF, DOCX, PPTX, Markdown, TXT, CSV, HTML, RTF, ODT, and ODP. Legacy binary DOC/PPT files are rejected instead of being guessed at unsafely.
- Built-in Skills cover classroom source reading, classroom document authoring, and study design.
- Native document generation supports Markdown, DOCX, PPTX, and PDF.
- PDF page boundaries and PowerPoint slide boundaries are retained during extraction so answers can remain traceable.
- All conversations share only the course foundation. Message history is loaded strictly by the active
thread_id, and project switching filters conversations by project.
sequenceDiagram
participant User
participant UI as Desktop UI
participant Host as Tauri command
participant Runtime
participant Store as SQLite event store
participant Worker as Isolated worktree
participant Verifier
participant Workspace
User->>UI: Submit objective
UI->>Host: Typed request
Host->>Store: Append RunCreated transaction
Host->>Runtime: Execute bound run
Runtime->>Store: Append plan and context events
Runtime->>Worker: Execute scoped tools
Worker->>Store: Persist tool calls, patches, evidence
Runtime->>Verifier: Verify integrated result
Verifier->>Store: Append criterion verdicts
alt verified
Runtime->>Workspace: Atomic write-through
Runtime->>Store: Append delivery event
else incomplete or approval required
Runtime-->>UI: Preserve state and request intervention
end
Store-->>UI: Projected snapshot and deltas
The backend is authoritative. The store uses SQLite WAL and append-only events, allocates per-run sequence numbers transactionally, and updates projections in the same transaction. Frontend state is rebuilt from backend snapshots and deltas.
Tool boundaries are deliberately narrow:
| Capability | Main guard |
|---|---|
| Read/search files | Canonical paths must remain below the worker workspace; reads and result counts are bounded. |
| Write documents/files | Safe relative paths, symlink checks, size limits, atomic writes, and explicit overwrite behavior. |
| Patch files | Expected SHA-256 and exact-match constraints prevent stale or ambiguous edits. |
| Run a process | An executable and argument vector are passed directly; no implicit shell interpolation. |
| Import course material | Extension allowlist, file/count limits, cleaned names, hashes, and project-local copies. |
| Credentials | Provider secrets are stored in Windows Credential Manager rather than the SQLite database. |
| Delivery | User workspace changes occur only after independent verification. |
LunaScope/
├─ apps/desktop/src-tauri/ Tauri host, commands, windows, built-in Skills
├─ crates/lunascope-core/ Domain types, IDs, events, policy, projections
├─ crates/lunascope-store/ SQLite event and metadata persistence
├─ crates/lunascope-provider/ Model transports, SSE, credentials
├─ crates/lunascope-runtime/ Agents, scheduler, worktrees, tools, documents, MCP
├─ src/ Vanilla TypeScript desktop UI
├─ scripts/ Windows release helpers
├─ docs/ Architecture, research, audit, and design notes
└─ release/v0.5.0/ Installer, portable executable, notes, checksums
- Open the v0.5.0 release.
- Download
LunaScope-0.5.0-windows-x64-setup.exe. - Run the installer. Installation is per-user and does not require an administrator account.
- Start LunaScope, configure a provider, create a project, and begin a conversation.
Download LunaScope-0.5.0-windows-x64-portable.exe and run it directly. Microsoft Edge WebView2 Runtime is required.
Verify either download against release/v0.5.0/SHA256SUMS.txt:
Get-FileHash -Algorithm SHA256 .\LunaScope-0.5.0-windows-x64-setup.exe- Open Settings and create a model provider configuration. API keys are written to Windows Credential Manager.
- Create a General project for repository work, or an UltraNote project for a course.
- For UltraNote, enter the course code and name, optionally add a description, and import the syllabus or class material.
- Create one or more conversations. Course background is shared, while each conversation remains independent.
- Submit an objective. Use the orchestration and changes views to inspect progress, evidence, and proposed delivery.
Application data defaults to %LOCALAPPDATA%\LunaScopeNext. Project files remain in the workspace chosen by the user.
- Windows 10/11 x64
- Rust 1.95 or newer
- Node.js 20 or newer and npm
- Git
- Microsoft Edge WebView2 Runtime
git clone https://github.com/LagrangeNSS/LunaScope.git
cd LunaScope
npm ci
npm run build
cargo fmt --all -- --check
cargo test --workspace --all-targets --locked
npm run tauri:devnpm run tauri:installerThe portable executable is written to target/release/lunascope-desktop.exe; the NSIS installer is written below target/release/bundle/nsis/.
- 78 Rust tests passed.
- 0 tests failed.
- 4 live-provider network tests are ignored by default because they require external credentials and network access.
- TypeScript type checking and the Vite production build passed.
- Tauri release and NSIS installer builds passed.
- The actual desktop application was used to create General and UltraNote projects, import course sources, switch projects, verify independent threads, restart, and confirm persisted state.
See the final audit, the UltraNote audit, and the orchestration research for implementation evidence and design rationale.
Version 0.5.0 is Windows-first and ships unsigned binaries. Windows may display a reputation warning for a newly downloaded executable. Review the published source and SHA-256 checksums before running it. A configured external model provider is required for agent execution; live-provider calls may incur provider charges.