ARCHiTEXT

The bridge between your Obsidian vault and LLMs.
A high-performance Ruby TUI for context stitching.

---

ARCHiTEXT is a standalone Ruby TUI for stitching Obsidian notes into an LLM-friendly Markdown context bundle. It uses the official obsidian CLI as the source of truth for vault search and file reads, providing a visual terminal interface for selecting notes.

🚀 Quick Start

# Start the interactive search and selection flow
architext

ARCHiTEXT will detect your active Obsidian vault, ask for a search query, then open a picker where you can select notes and copy the stitched context bundle to your clipboard.

Common next steps:

# Search with a specific query
architext --query "game"

# Search a specific vault
architext --vault "Main Vault" --query "project"

# Print the bundle instead of copying it
architext --query "tag:#project/active" --all --stdout

✨ Features

• Visual Picker: Interactively select notes using a high-performance ANSI TUI.
• Vault-Aware UX: Active vault is always visible in the TUI, with inline vault switching.
• Context Stitching: Automatically bundles selected notes into a single Markdown file.
• LLM Ready: Output is formatted specifically for easy consumption by AI agents.
• No Dependencies: Built-in ANSI-based TUI logic (no complex visual gems required).
• Cross-Platform Clipboard: Uses native clipboard commands on macOS, Windows, and Linux.

📦 Installation

Using RubyGems

gem install architext
architext --version
gem uninstall architext

From Source

git clone https://github.com/CanPixel/ARCHiTEXT.git
cd ARCHiTEXT
./bin/setup
ruby bin/architext --version
gem build architext.gemspec
gem install ./architext-*.gem

⚙️ Configuration

Architext relies on the Obsidian CLI. Ensure it is installed and available on your PATH.

Supported Platforms

• macOS: Fully supported (tested in CI).
• Windows: Native terminal support (PowerShell/Windows Terminal) with clip clipboard integration.
• Linux: Native terminal support with clipboard integration via wl-copy, xclip, or xsel.

Setting the Obsidian CLI Path

If the CLI is not in your PATH, you can set the ARCHITEXT_OBSIDIAN environment variable:

export ARCHITEXT_OBSIDIAN="/path/to/obsidian"

PowerShell:

$env:ARCHITEXT_OBSIDIAN = "C:\path\to\obsidian.exe"

🛠 Usage

# Basic interactive search
architext

# Search with a specific query
architext --query "Zombie Parkour"

# Output directly to stdout (useful for piping)
architext --query "tag:#ctx/current" --stdout | gemini "Summarize this"

# Specify a vault
architext --vault "Main Vault" --query "Ideas"

# Set a persistent default vault
architext --set-default-vault "Main Vault"

# Clear the persistent default vault
architext --clear-default-vault

# Check exactly which executable version is running
architext --version

# Print vault/CLI diagnostics before searching
architext --diagnose

# Skip the picker and include all results
architext --query "tag:#project/active" --all --stdout

Vault Selection Behavior

• --vault sets the vault only for the current run.
• --set-default-vault stores a persistent default vault for future runs.
• If --vault is omitted, the persistent default vault is used when available.
• At the search prompt, type v to open vault configuration mode.
• Press v in the TUI selection screen to change vault inline for the current session.
• The active vault is shown in the TUI header (vault: ...) so target scope is always visible.
• Vault path resolution is performed by the Obsidian CLI (vault=<name_or_id>); ARCHiTEXT displays the vault reference and source.
• Startup prompt includes an Obsidian connection check (version, resolved vault summary, executable path).

Search Prompt Controls

Input	Action
enter	Run search with default query
v	Open vault configuration screen
q	Quit

TUI Controls

Key	Action
↑/k, ↓/j	Move selection
space	Toggle selection for current note
a	Toggle all visible notes
/	Filter current results
n	Start a new Obsidian search
v	Set/change active vault
enter	Confirm and bundle selected notes
q	Return to search prompt

🔍 Troubleshooting

Obsidian CLI Not Found

If you see an error about obsidian command not found:

1. Ensure the Obsidian desktop app is installed.
2. Verify that you have installed the obsidian CLI tool.
3. Check if obsidian is in your PATH by running which obsidian (macOS/Linux) or where obsidian (Windows).
4. If you previously exported OBSCTX_OBSIDIAN, rename it to ARCHITEXT_OBSIDIAN.

No Results But Notes Exist

• Verify the active vault shown in the TUI header.
• At the search prompt, type v to open vault configuration.
• In selection, use v to switch vault and rerun the query.
• Set a persistent vault with --set-default-vault "Your Vault".
• For one-off runs, pass --vault "Your Vault" explicitly.
• Run architext --diagnose to print the exact vault reference/source and Obsidian CLI resolution before searching.

Clipboard Issues

Architext auto-detects clipboard tools:

• macOS: pbcopy
• Windows: clip (fallback: PowerShell Set-Clipboard)
• Linux: wl-copy, xclip, or xsel

If none are available, run with --stdout and pipe output to your preferred clipboard manager.

📜 License

Architext is released under the MIT License.