Getting Started with Ars Umbris: Install and Explore a Typed, Agent-Native IDE

What Is Ars Umbris?

Ars Umbris is a malleable, agent-native IDE for typed knowledge. It combines knowledge, types, skills, tools, and UI components in composable repositories that can depend on one another.

The project reads these repositories as a single typed graph. It checks fields and references, then provides diagnostics that agents can act on. Humans and agents can use the same primitives and SDKs to build tools, add views, and modify the application.

Ars Umbris is currently an early alpha, so expect bugs and breaking changes. It currently supports macOS only.

How the Architecture Fits Together

Ars Umbris is organized into three main layers. Understanding them helps you decide where to look when configuring or extending the system.

1. au-engine

au-engine is the cross-repository graph engine built over a typed file substrate. It indexes files across repositories and turns them into a typed, queryable, live graph.

The engine also implements a custom typing language for Markdown and YAML files. For more detail, read au-engine.md.

2. au-host

au-host is the Electron host application. It mounts typed projections, or views, over the graph and supports configuration-driven compositions over typed data.

These compositions are editable and can be driven by both humans and agents. See au-host.md for the host documentation.

3. au-mcp

au-mcp provides the extensible agent layer. It exposes typed tools and skills through MCP and interfaces with your agent harness of choice through adapters.

Read au-mcp.md to learn more about the MCP layer.

Prepare for Installation

The installation process uses two directories:

• ~/arsumbris/ holds multiple Ars Umbris repositories.
• ~/.arsumbris/ holds Ars Umbris configuration files.

Because the project is macOS-only and still in active development, review the prerequisites before making system changes. The repository's current installation instructions are the authoritative source for required software and setup order.

Install the Entry-Point Repository

The README recommends asking your agent to perform the installation with the following instructions:

Please help me install Ars Umbris.

1) Create two folders if they do not already exist:
   - ~/arsumbris/ will hold multiple repositories.
   - ~/.arsumbris/ will hold configurations.

2) Clone the entry-point repository:
   git clone https://github.com/arsumbris/arsumbris.git ~/arsumbris/arsumbris
   If that destination already exists, inspect it before proceeding; do not overwrite it.

3) Read ~/arsumbris/arsumbris/INSTALL.md and follow its current setup process.
   Check prerequisites and explain any changes needed on my machine before making them.

The important safety step is to inspect an existing ~/arsumbris/arsumbris directory before cloning. Do not overwrite an existing checkout. After the repository is available, open INSTALL.md and follow its current instructions in the documented order.

Follow the Repository's Current Setup Process

1. Confirm that you are using macOS.
2. Create ~/arsumbris/ and ~/.arsumbris/ if they do not already exist.
3. Check whether ~/arsumbris/arsumbris already exists.
4. If it does not exist, clone the repository with git clone https://github.com/arsumbris/arsumbris.git ~/arsumbris/arsumbris.
5. If it already exists, inspect it rather than replacing it.
6. Read ~/arsumbris/arsumbris/INSTALL.md.
7. Check and install the prerequisites specified by that file, reviewing proposed machine changes before applying them.
8. Complete the remaining setup steps in the order documented by INSTALL.md.

Since Ars Umbris is under active development, avoid relying on outdated setup instructions from third-party sources. Use the checked-out repository's installation guide for the version you are installing.

Basic Usage Concepts

Ars Umbris is designed around repositories containing typed knowledge and capabilities. A repository can contain knowledge, type definitions, skills, tools, and UI components. Repositories can also depend on other repositories, allowing capabilities and knowledge to be reused across projects.

At a high level, a typical workflow looks like this:

1. Place or clone related repositories under ~/arsumbris/.
2. Let au-engine index the file substrate across those repositories.
3. Use the resulting typed graph to work with connected data, fields, and references.
4. Use au-host to mount projections and views over the graph.
5. Connect an agent harness through au-mcp and MCP adapters.
6. Use agents or human users to inspect diagnostics, build tools, add views, and modify the application.

The README does not prescribe a single sample project or command-line workflow. Your exact commands and available projections depend on the setup described in INSTALL.md and the repositories you connect.

Working with Agents Through MCP

Ars Umbris is built to connect with an agent harness through the Model Context Protocol. The au-mcp layer provides typed tools and skills, while adapters connect those capabilities to the harness you choose.

This lets an agent work with the same underlying primitives and SDKs used to build the application. In practice, an agent can participate in building tools, adding views, and modifying the app, subject to the capabilities and configuration available in your installation.

Advanced Tips and Safety Considerations

Keep Repositories Composable

Organize knowledge and capabilities into repositories that can be reused and connected. Cross-repository dependencies are a central part of the project model, so think of the repositories as parts of one typed graph rather than isolated folders.

Use Diagnostics as Feedback

The engine checks fields and references across the typed graph. Treat its diagnostics as feedback when editing typed Markdown, YAML, or related repository content, especially when an agent is making changes.

Read Layer Documentation

When you need to understand behavior, consult the documentation for the relevant layer: engine, host, or MCP agent layer.

Review Changes Before Applying Them

The installation prompt specifically recommends explaining required machine changes before making them. Follow the same cautious approach when allowing agents to modify repositories or configuration.

Account for the Current Security Model

Ars Umbris runs code on your machine and currently has no sandboxing. Review SAFETY.md before using the project, particularly when connecting agents or working with repositories you do not fully control.

Conclusion

Ars Umbris combines a typed cross-repository graph, an Electron-based host, and an MCP agent layer into an experimental IDE for typed knowledge. To get started, prepare the two configuration directories, clone the entry-point repository without overwriting existing files, and follow its current INSTALL.md. Once installed, explore how repositories, projections, tools, skills, and agents work together—while keeping the project's alpha status and unsandboxed execution model in mind.