tiles

A local-first, collaborative AI assistant that works for you. Built with open models and decentralized protocols. www.tiles.run

Fork

tiles HACKING.md

4.4 kB · 154 lines

Markdown

at main

Harsh Sharma · menu bar app for macOS (#200) · 1mo ago

4590fd35

HACKING.md #

This guide will help you set up a reproducible development environment for Tiles. Tiles supports two environments: prod (production) and dev (development). These instructions assume you are setting up for local development.

Prerequisites #

Rust & Cargo
just (for task management)
Python 3.13
uv (for fast Python dependency management)
Git

Setup Steps #

Clone the repository:

git clone https://github.com/tilesprivacy/tiles.git
cd tiles

Install Rust dependencies:

If you're new to Rust, see Rust Install Guide.
```
cargo build
```

Install project task runner:

just provides easy command shortcuts.

cargo install just      # or use your OS package manager

Set up the Python server environment:
- Make sure uv is installed:
```
pip install uv
```
- Sync Python dependencies:
```
cd server
uv sync
cd ..
```
Provision the inference engine:

Tiles runs inference through a llama-server binary. Fetch it for your platform:
```
./scripts/fetch_llama_server.sh
```
- macOS: downloads the official prebuilt Metal release into server/bin/.
- Linux: builds llama-server from source, with CUDA when nvcc is available (CPU otherwise).
Then symlink the dev assets into .tiles_dev/tiles/:
```
./scripts/setup_dev_layout.sh
```
The default model (unsloth/gemma-4-12b-it-GGUF, Q4_K_M) is downloaded automatically on the first cargo run. A different quantization can be selected in the modelfile with FROM unsloth/gemma-4-12b-it-GGUF:Q8_0 (ollama-style tag). MTP speculative decoding auto-enables when the model ships an MTP head (mtp-*.gguf next to the main model); disable with [llama] mtp = false in config.toml.

Embedding Pi #

Pi is a minimal coding agent for agentic harness. We embed Pi in Tiles so that it can sit in between the CLI and inference layer to provide more powerful features for the regular knowledge work, agent harness and whatever that comes in future is just an extension away thus making Tiles flexible and can ride the wave of standards.

Current approach on how we integrate Pi is, we pack the pi bun binary with the tiles installer and use Pi in rpc mode from Tiles. So Pi interacts with the Tiles model inference and communicates with the Tiles Pi via stdin, stdout json.

Setting up PI #

For development, Tiles expect a pi folder under .tiles_dev/tiles/ (This folder is created first time when we run tiles from the root directory with cargo run). We can run just build_w_pi which will handle downloading and extracting the relevant Pi binary.

Running Tiles (Development) #

Open two terminal windows:

Terminal 1: Start the server

From the project root:
```
just serve
```
Terminal 2: Run the Rust CLI

From the root directory:
```
cargo run
```

Tip: Refer to the justfile for additional common commands and automation. For troubleshooting, see CONTRIBUTING.md and open an issue if you need help.

The menu bar app lives in apps/menubar. It needs pnpm.

Open two terminal windows:

Terminal 1: Start the daemon

From the project root:
```
cargo run -- daemon --no-ui
```
Terminal 2: Run the app

From the root directory:
```
pnpm --filter tiles-menubar tauri dev
```

Building Tiles installer (Development) #

Install venvstacks for portable py runtime

From the project root do,

just bundle # Creates the compressed zip in dist/

Set the ENV in install.sh to dev

just install

Now tiles should be available in PATH