Documentation
Houston is an agile-centric, AI-powered native code editor built exclusively for macOS. This guide covers everything from installation to advanced workflow automation.
Installation
Houston is currently in early access. You can download the latest Disk Image (DMG) from our downloads section.
Once downloaded, drag the application to your Applications folder.
$ brew install --cask houston-editor(Homebrew formula coming soon)
Configuration
Houston uses a houston-config.json file in the root of your project to define workspace settings.
This allows you to share project-specific configurations with your team.
{
"projects": [
{
"name": "My Backend",
"platform": "vapor",
"root": "Sources/App",
"include": ["**/*.swift"]
}
],
"embeddingModel": "text-embedding-ada-002",
"neighborCount": 50
}
The platform field determines which compiler (Swift vs. Dart/Flutter) is used for the auto-compile checks.
Authentication
Houston uses secure, passwordless authentication via Passkeys (WebAuthn). When you first launch the app, you will be prompted to create an account or sign in using Touch ID or Face ID.
The Interface
Houston is designed around a three-pane layout to balance planning, communication, and execution.
- Agile Ticket Pane (Top/Left): This is your project management center. It displays the Kanban board where tasks move from Backlog to Work Queue to Completed.
- Chat Assistant (Bottom Left): This is your interface to the AI. You can chat about code, or command the AI to write code based on your tickets.
- Code Editor (Bottom Right): A lightweight, native Source Editor with syntax highlighting and live diff views.
Visibility Controls: You can toggle any of these panes using the toolbar icons or keyboard shortcuts to focus on specific tasks.
Agile Workflow
Unlike traditional editors, Houston is aware of your development cycle. It includes a native Kanban board that integrates directly with your code changes.
The Kanban Board
- Backlog: Where ideas and tasks live. Items here are static.
- Work Queue: When a ticket is moved here, it becomes "Active." If the AI is idle, it will pick up the top ticket in the Work Queue and begin processing it automatically.
- Completed: Once the AI finishes the changes and the code compiles, the ticket moves here automatically with a summary of changes and a Git diff.
Creating Tickets
Tickets drive the AI. A well-defined ticket ensures the AI knows what to change and where.
Tip: You can right-click any chat bubble or use the header icon in the expanded view to "Create Ticket from Message." This pre-populates the Ticket Summary with the chat content, allowing for a fluid workflow from discussion to action.
AI Assistant
Houston clearly distinguishes between planning code and writing code via two distinct modes found in the chat interface.
Coding Mode
- Purpose: Action-oriented.
- Behavior: The AI has write-access to your files. When you prompt it, it will attempt to generate code, apply it to the selected file, compile it, and run a diff.
- Workflow: Select files → Type Prompt → AI Writes Code → Auto-Compile → Diff Review.
Conversing Mode
- Purpose: Planning and Q&A.
- Behavior: The AI is read-only. It uses the chat history and project context to answer questions, explain concepts, or help you debug logic without modifying your files on disk.
Semantic Index
Houston indexes your codebase locally to enable Semantic Search (RAG). This ensures only relevant files are sent to the LLM as context. Users can manually trigger a re-index if search results feel stale by clicking the refresh icon in the File Browser.
Editor Features
Diff View: Toggle between the raw editor and the Git Diff view to see exactly what the AI changed. Use the toggle button in the bottom-right corner of the editor pane.
Live Compilation: Houston runs a lightweight compiler process in the background. It checks your syntax and types as you type, offering real-time fix-its powered by the underlying toolchain (e.g., SourceKit-LSP for Swift).
Keyboard Shortcuts
Reference table for power users.