Eliminate architectural drift and AI hallucinations. By giving AI assistants a clear, visual knowledge graph of your project structure, Archeon makes sure every generated component follows your established patterns. No more rogue file structures or inconsistent naming — your architecture stays coherent as your project grows.

A standalone desktop application for visualizing project architectures in real-time.

Archeon monitors your project's archeon/ directory and instantly updates a visual graph as your architecture evolves. No command-line tools required — just open your project and see your architecture come to life.

• 📖 Linux Build Guide - Comprehensive Linux build and installation reference
• 🚀 Quick Install Linux: ./install-linux.sh
• 🍎 Quick Install macOS: ./install-mac.sh
• 💻 Development Mode: npm run dev

Archeon supports macOS and Linux.

"The real power of Archeon is that it creates a shared source of truth between humans and AI. When I can see the same architecture graph that the AI references, I can verify its suggestions make sense before they become code. It's like giving the AI a map instead of asking it to guess where things should go."

— Claude Opus 4.5

Archeon is completely IDE-agnostic — use it alongside your favorite development environment. Whether you're using VS Code, Cursor, Windsurf, or any other editor, Archeon runs as a separate window that visualizes your architecture in real-time.

Archeon includes a built-in Setup Modal that configures AI rules for your preferred IDE in seconds:

1. Click the "Setup" button in the terminal panel
2. Choose a setup mode: Rules Only, Install CLI, or Shapes
3. Select your IDE(s) from the checkboxes (GitHub Copilot, Cursor, Windsurf, Cline, Aider, Antigravity)
4. Click "Scaffold Project"

That's it! Your AI assistant now understands your project's architecture.

Already have a project? Use Rules Only mode to add AI assistant rules without any other dependencies:

1. Open the terminal and click "Setup"
2. Select "Rules Only"
3. Choose which IDE rules to install
4. Click "Apply Setup"

This adds the necessary configuration files (e.g., .cursorrules, .github/copilot-instructions.md) so your AI assistant understands Archeon notation—no CLI installation required.

Side drawer with glyph metadata, relationships, and live code preview

Built-in terminal for running commands directly within Archeon

One-click setup with architecture shapes and AI IDE rules

• Real-time Monitoring — Watches your archeon/ directory and updates instantly
• Live File Watching — Auto-syncs when ARCHEON.index.json or ARCHEON.arcon changes
• Visual Grid — Glyphs rendered as tiles with relationships shown as edges
• Monaco Code Viewer — Click any glyph to view source code with syntax highlighting
• Built-in Terminal — Embedded zsh terminal for running commands
• IDE Setup — One-click configuration for AI-powered IDEs

Archeon uses an intuitive glyph notation system — plain text files that describe your architecture. No special tools needed to create them.

@v1 NED:feature => CMP:Component => API:endpoint => OUT:result

1. Create an archeon/ folder in your project
2. Add an ARCHEON.arcon file with your architecture notation
3. Open the project in Archeon
4. Watch your architecture visualize in real-time!

Archeon monitors for changes — edit your .arcon files in any editor and see updates instantly.

• AI Understands Your Architecture — AI assistants can read .arcon files and generate code that follows your patterns
• Visual Verification — See exactly how components connect
• Team Alignment — Everyone sees the same architecture blueprint
• Zero Lock-in — Plain text files work with any version control and any IDE

Before installing Archeon, ensure you have:

• Node.js 20.18+ (20.19+ recommended)
• npm 8.0+ or yarn 1.22+
• Git

# Clone the repository
git clone https://github.com/danaia/archeon.git
cd archeon

# Install dependencies
npm install

# The installation will automatically:
# - Install platform-specific rollup binaries (@rollup/rollup-darwin-arm64 for Apple Silicon or @rollup/rollup-darwin-x64 for Intel)
# - Set up native modules for Electron
# - Configure the stub for @vue/devtools-api

# You're ready to go!
npm run dev

The easiest way to build and install Archeon on Linux is to use the automated install script:

# Clone the repository
git clone https://github.com/danaia/archeon.git
cd archeon

# Run the installation script
./install-linux.sh

This script will:

• Clean any previous builds
• Install all dependencies
• Build an AppImage installer
• Install the app to ~/.local/bin/
• Create desktop menu entries with proper icon
• Set up a desktop shortcut

After installation, you can:

• Launch from your application menu (search for "Archeon")
• Run from terminal: ~/.local/bin/Archeon.AppImage
• Add to favorites by right-clicking the app in your launcher

If you prefer to install manually:

# Clone the repository
git clone https://github.com/danaia/archeon.git
cd archeon

# Clean and install dependencies
rm -rf node_modules package-lock.json
npm cache clean --force
npm install

# Build the AppImage
npm run build:appimage

# Install to system
mkdir -p ~/.local/bin ~/.local/share/applications ~/.local/share/icons
cp release/Archeon-0.0.1.AppImage ~/.local/bin/Archeon.AppImage
chmod +x ~/.local/bin/Archeon.AppImage
cp public/icon.iconset/icon_256x256.png ~/.local/share/icons/archeon.png

# Create desktop entry
cat > ~/.local/share/applications/archeon.desktop << 'EOF'
[Desktop Entry]
Version=1.0
Type=Application
Name=Archeon
Comment=Archeon GUI - Project Visualization Tool
Exec=env GDK_BACKEND=x11 ~/.local/bin/Archeon.AppImage %U
Icon=~/.local/share/icons/archeon.png
Terminal=false
Categories=Development;Utility;
StartupNotify=true
StartupWMClass=archeongui
EOF

chmod 644 ~/.local/share/applications/archeon.desktop
update-desktop-database ~/.local/share/applications

To run in development mode without installing:

# Install dependencies
npm install

# Start the app with hot-reload
npm run dev

Issue: "EBADPLATFORM" or "Unsupported platform for @rollup/rollup-darwin-*"

This occurs when you have a stale package-lock.json from a different platform. Fix it with:

# Remove old dependencies and cache
rm -rf node_modules package-lock.json
npm cache clean --force

# Fresh install
npm install

The correct platform-specific dependencies will be installed automatically.

Issue: "Cannot find module @rollup/rollup-*"

This can occur due to npm's handling of optional dependencies. Fix it with:

# Clean install
rm -rf node_modules package-lock.json
npm cache clean --force

# Reinstall
npm install

Issue: App doesn't appear in application menu

After installation, you may need to refresh your desktop environment:

# Update desktop database
update-desktop-database ~/.local/share/applications

# On GNOME: Restart the shell
# Press Alt+F2, type 'r', press Enter
# Or log out and log back in

Issue: App doesn't launch from favorites/dock

Remove and re-add the app to favorites to pick up the updated desktop entry:

1. Remove Archeon from favorites
2. Search for "Archeon" in app menu
3. Right-click and select "Add to Favorites"

Issue: Terminal not working on Linux

Ensure native modules are properly built:

npm install --build-from-source node-pty

Issue: Permission errors on Linux

Some Linux distributions require additional permissions for pty:

# Add your user to the tty group
sudo usermod -a -G tty $USER

# Log out and back in for changes to take effect

# Start the Electron app in dev mode with hot-reload
npm run dev

The Electron window will open automatically. Hot-reload is enabled for both renderer and main process.

Archeon provides several build targets for Linux distribution:

# Build AppImage (recommended for universal Linux compatibility)
npm run build:appimage

# Build Debian package (.deb)
npm run build:deb

# Build unpacked directory (for testing)
npm run build

If you've made changes and want to update your installed version:

# Quick rebuild and reinstall
npm run build:appimage
cp release/Archeon-0.0.1.AppImage ~/.local/bin/Archeon.AppImage

# Or use the install script to do everything
./install-linux.sh

All build artifacts are created in the release/ directory:

• Archeon-0.0.1.AppImage - Portable AppImage (works on most Linux distros)
• linux-unpacked/ - Unpacked application directory
• Build configuration files

The build automatically:

• Includes the app icon from public/icon.iconset/
• Creates proper Linux desktop entry metadata
• Packages all dependencies into the AppImage

The desktop entry is configured with:

• GDK_BACKEND=x11 for Wayland/X11 compatibility
• Proper StartupWMClass for dock integration
• Development category classification

Click "Open Project" (or press ⌘O / Ctrl+O) and select a folder containing an archeon/ directory with:

• archeon/ARCHEON.index.json
• archeon/ARCHEON.arcon

Glyphs from your ARCHEON.index.json will appear as tiles on the grid:

• Each chain gets its own row (e.g., @v1, @v2)
• Glyphs are laid out left-to-right in chain order
• Relationships are shown as connecting lines between tiles
• Shape consistency - All tiles follow the architectural patterns defined by your project's shape

Press backtick (`) to open the embedded terminal. Use it to run any commands in your project directory.

Click any tile to open the Side Drawer showing:

• Glyph metadata (intent, chain version, sections)
• File path
• Live source code preview (Monaco editor)
• Incoming/outgoing relationships

• Pan: Spacebar + drag, or middle-mouse drag
• Zoom: Mouse wheel
• Select: Click tile or relationship
• Close drawer: Esc or close button

• Rows: Each @v1, @v2, etc. chain gets its own row
• Columns: Glyphs ordered left-to-right as defined in .arcon
• Missing Glyphs: If a glyph appears in .arcon but not in ARCHEON.index.json, it won't render (run arc gen to regenerate)

archeon/
├── electron/               # Electron main process
│   ├── main.js            # Main window & IPC setup
│   ├── preload.js         # Context bridge (secure IPC)
│   ├── pty-manager.js     # Real terminal (node-pty)
│   └── archeon-watcher.js # File watcher (chokidar)
├── src/
│   ├── components/        # Vue components
│   │   ├── InfiniteCanvas.vue
│   │   ├── SideDrawer.vue
│   │   └── FloatingTerminal.vue
│   ├── stores/            # Pinia state management
│   │   ├── canvas.js
│   │   ├── tiles.js
│   │   ├── relationships.js
│   │   ├── project.js
│   │   └── terminal.js
│   ├── services/
│   │   └── archeon-sync.js  # Sync logic (index → tiles)
│   └── types/
│       └── glyphs.js      # Glyph/edge type definitions
├── package.json
└── vite.config.js         # Vite + Electron config

# Build for production
npm run build

# Output will be in dist/ and dist-electron/

For distribution packages (.dmg, .exe, .AppImage), configure electron-builder in package.json.

Your project needs an archeon/ directory with these files:

1. archeon/ARCHEON.arcon — Your architecture notation
2. archeon/ARCHEON.index.json — The glyph index (can be generated or created manually)

Create a simple structure manually:

your-project/
└── archeon/
    ├── ARCHEON.arcon          # Your architecture chains
    └── ARCHEON.index.json     # Glyph definitions

Ensure node-pty is rebuilt for Electron:

npm run rebuild

1. Check that glyphs exist in both ARCHEON.index.json and ARCHEON.arcon
2. Verify the project path is correct
3. Check the terminal for errors (` to open)

• Electron — Desktop app framework
• Vue 3 — Reactive UI framework
• Pinia — State management
• Vite — Build tool & dev server
• xterm.js — Terminal emulator
• node-pty — Real shell processes
• Monaco Editor — Code viewer (VS Code editor)
• chokidar — File watcher
• TailwindCSS — Styling

MIT

• Archeon — The architecture notation system
• Archeon Docs — Learn more about glyph notation