Core Engine: File System & Git
Relevant source files
The following files were used as context for generating this wiki page:
The Core Engine provides the fundamental infrastructure for interacting with the host machine's file system and Git repositories. Within the Atmos ecosystem, these modules are responsible for managing project files, tracking changes, and enabling AI-driven documentation workflows. The engine abstracts complex operations into high-level APIs that support workspace management, file manipulation, and Git-based versioning.
These systems are critical for the functionality of "Skills" like the Project Wiki, which relies on the engine to perform deep research into the codebase, collect metadata, and persist generated Markdown content. By combining local file access with Git history analysis, the Core Engine enables a research-grade understanding of the project's evolution and architecture.
File System (FS) Module
The FS module handles low-level file operations and directory management. It is designed to provide a secure and efficient way to read, write, and traverse files within a workspace.
Key Operations and Logic
The system supports standard I/O operations tailored for project management:
- File Reading/Writing: Facilitates reading from and writing to project paths, including metadata files like
_catalog.jsonused by the Wiki system. - Path Resolution: Normalizes paths based on
workspacePathorprojectPathto ensure operations stay within defined boundaries. - Recursive Discovery: Scans directories for specific file types (e.g.,
.rs,.ts) to build a map of the project structure for AI research.
Sources: crates/core-engine/src/fs/mod.rs, specs/tech/project-wiki.md:105-115
Data Flow: File Reading
The following diagram illustrates how the frontend requests and receives file content through the WebSocket API.
Sources: specs/tech/project-wiki.md:325-345
Git Integration Module
The Git module provides an interface to the project's version control system. It is primarily used for metadata collection, change detection, and incremental updates.
Core Git Functionalities
| Function | Description |
|---|---|
get_head_commit | Executes git rev-parse HEAD to retrieve the current unique commit SHA. |
collect_metadata | Gathers commit logs, contributor lists, and file statistics into _metadata/. |
get_diff | Identifies changed files between two commits for incremental updates. |
Sources: crates/core-engine/src/git/mod.rs, specs/tech/wiki_incremental_update.md:58-65
Git Metadata Collection
The engine runs scripts to output Git history into specific text and JSON files for AI context:
commit_graph.txt:git log --oneline --graphcommit_details.txt: Full log with file statistics.contributors.txt:git shortlog.
Sources: crates/core-engine/AGENTS.md, specs/tech/wiki_incremental_update.md:154-165
Wiki Generation & Incremental Updates
A primary consumer of the FS and Git modules is the Project Wiki system. It uses the engine to determine when documentation is out of sync with the codebase.
Change Detection Workflow
The engine enables incremental updates by tracking the commit_hash within a _catalog.json file. When the current HEAD differs from the recorded hash, the system triggers a diff analysis.
Incremental Update Strategy
The system partitions changed files into categories to minimize regeneration:
- Source-Matched: Files explicitly listed in a page's frontmatter.
- Uncovered: Files not previously documented that require AI reasoning to categorize.
- Cross-Cutting: Shared utilities or core abstractions that impact multiple modules.
Sources: specs/tech/wiki_incremental_update.md:215-235
Technical Specifications
API Interface
The engine exposes several WebSocket actions for external consumption by the Atmos UI.
| WsAction | Parameters | Return Type |
|---|---|---|
FsReadFile | path: String | { content: String } |
GitGetHeadCommit | path: String | { commit_hash: String } |
Sources: specs/tech/wiki_incremental_update.md:50-70, specs/tech/project-wiki.md:105-110
Error Handling
The Git engine includes safety checks for non-git projects and repository state:
- Force Pushes: If the stored commit is no longer in history, the engine returns an error prompting a full regeneration.
- Non-Git Projects: Returns a specific error code to the frontend to disable Git-dependent UI elements.
Sources: specs/tech/wiki_incremental_update.md:275-285
Summary
The Core Engine's File System and Git modules provide the technical foundation for Atmos's intelligent documentation and codebase management. By abstracting local disk access and version control history, the engine allows AI agents to perform deep research and maintain a synchronized, high-quality technical wiki. The implementation emphasizes performance through incremental updates and reliability through strict validation of commit history and file structures.