0.1.2 • Published 22h agoCLI

layrx

Licence

MIT

Version

0.1.2

Deps

Size

241 kB

Vulns

Weekly

Summary Dependency Versions

LayrX

Repository intelligence and grounded AI for developers.

Latest release: 0.1.2

LayrX indexes your Git repository locally — files, symbols, dependencies, and embeddings — then powers semantic search, grounded AI chat, and a web dashboard. Your code stays on your machine; only AI provider API calls leave your network when you connect a provider.

Website: https://layrx.dev/
npm: https://www.npmjs.com/package/layrx
GitHub: In Progress...

Install

npm install -g layrx@latest

Or pin a specific version:

npm install -g layrx@0.1.2

Requirements

Requirement	Details
Node.js	20 or later (`node -v`)
Git	Required for `layrx init` (current directory must be a Git repo)
OS	macOS, Linux, or Windows
Build tools	May be required on some platforms for native indexing modules (same as other Node native addons)

Verify the install:

layrx --version

Quick start

Run these commands in order:

# 1. Install the CLI globally
npm install -g layrx@latest

# 2. cd into your Git project (not your home directory)
cd /path/to/my-project

# 3. Start the local agent (gateway + dashboard UI on port 8765)
layrx start

# 4. Initialize and index the repository
layrx init

# 5. Open the web dashboard
layrx dashboard

Then visit http://127.0.0.1:8765 in your browser.

Typical first-time flow inside the dashboard:

Open Settings → AI Providers and connect a provider (OpenAI, Anthropic, Gemini, Ollama, etc.).
Set a default provider and model.
Use AI Chat for grounded questions about your codebase.
Browse Repository views (overview, search, knowledge graph, symbols, dependencies).

How it works

LayrX runs as a local agent on your machine:

┌─────────────┐     HTTP      ┌──────────────────────────────────────┐
│  layrx CLI  │ ────────────► │  Local Agent (gateway) :8765         │
│  dashboard  │               │  • REST API                          │
└─────────────┘               │  • SQLite index (.layrx/layrx.db)    │
                              │  • Serves dashboard UI               │
                              └──────────────────────────────────────┘
                                         │
                                         ▼
                              ┌──────────────────────────────────────┐
                              │  Your Git repository (indexed)       │
                              └──────────────────────────────────────┘

layrx start launches the gateway process and writes state under .layrx/ in your current working directory when you start the agent. Run it from your project directory (or the directory where you want agent metadata stored), not from ~.
layrx init registers and indexes the Git repo you run it from; it requires the agent to already be running.
layrx dashboard opens the built-in web UI served by the gateway (not a separate dev server).

All repository indexing and search run locally. AI chat sends prompts to the provider you configure in Settings.

Commands

Agent lifecycle

Command	Description
`layrx start`	Start the local agent
`layrx stop`	Stop the local agent
`layrx restart`	Restart the local agent
`layrx status`	Show agent health, uptime, and module status
`layrx dashboard`	Open the dashboard in your browser

layrx start options

layrx start [--verbose] [--host <host>] [--port <port>]

Option	Default	Description
`--host`	`127.0.0.1`	Bind address for the gateway
`--port`	`8765`	HTTP port
`--verbose`	off	Print startup and health polling details

On success you will see the gateway URL and a reminder to run layrx dashboard.

layrx status options

layrx status [--json] [--verbose] [--host <host>] [--port <port>]

Use --json for scripting. Status includes repository index state and health of modules such as the indexer, knowledge graph, embeddings, and search.

layrx dashboard options

layrx dashboard [--host <host>] [--port <port>] [--no-open]

Option	Description
`--no-open`	Print the URL instead of opening a browser tab

The agent must be running; otherwise the command tells you to run layrx start first.

Repository setup

layrx init — Initialize LayrX in the current Git repository.

layrx init [--force] [--verbose] [--config <path>] [--host <host>] [--port <port>]

Option	Description
`--force`	Overwrite an existing `.layrx/config.json`
`--config <path>`	Write config to a custom path instead of `.layrx/config.json`
`--verbose`	Log API requests and responses

What init does

Verifies the local agent is reachable.
Creates .layrx/ with config.json, logs/, and cache/.
Registers the repository with the gateway.
Runs a full index (files, symbols, dependencies, embeddings).
Waits until the repository status is READY.

Prerequisites: Run layrx start before layrx init. The current directory must be inside a Git repository.

To re-index after large changes, run layrx init again (use --force if you need to replace config).

Search

layrx search — Semantic search over the indexed repository.

layrx search [options] <query...>

Examples:

layrx search "JWT authentication middleware"
layrx search --limit 5 --page 2 "database migration"
layrx search --json "error handling in API routes"
layrx search --interactive "React context provider"

Option	Default	Description
`--limit`	`10`	Results per page
`--page`	`1`	Page number
`--json`	off	Output raw JSON
`--interactive`	off	Pick a result or load the next page in the terminal
`--host` / `--port`	`127.0.0.1` / `8765`	Agent connection

Chat

layrx chat — Interactive or one-shot AI chat grounded in your indexed repository.

layrx chat [options] [message]

Examples:

layrx chat                                    # interactive REPL; type exit or quit to leave
layrx chat "Where is user authentication handled?"
layrx chat --provider openai --model gpt-4o "Summarize the API layer"

Option	Description
`--provider <name>`	Override default AI provider
`--model <name>`	Override default model
`--verbose`	Log API requests

Note: Connect a provider in the dashboard Settings first, or pass --provider / --model. The gateway uses your configured credentials; keys are stored locally by the agent.

Web dashboard

After layrx start, the dashboard is served at:

http://127.0.0.1:8765

Area	Path	Description
Repository overview	`/overview`	High-level repo stats and navigation
File viewer	`/file`	Browse and view source files
Semantic search	`/search`	Search UI (same index as `layrx search`)
Knowledge graph	`/graph`	Visual graph of code relationships
Symbols	`/symbols`	Functions, classes, and symbols explorer
Dependencies	`/dependencies`	Dependency structure
AI workspace	`/ai`	Grounded chat with context strategies and routing
Monitor	`/monitor`	Agent health, providers, and quick insights
Analytics	`/analytics`	Usage and activity analytics
Settings	`/settings`	Providers, AI preferences, repository options

AI providers

Open Settings → AI Providers in the dashboard to connect:

Provider	Notes
OpenAI	API key required
Anthropic	API key required
Google Gemini	API key required
Ollama	Local models; set base URL if not default
Groq	API key required
DeepSeek	API key required
Azure OpenAI	API key + endpoint
Cursor	Cloud Agents API key — monitoring / agent workflows only

Important: Cursor and chat

Do not use Cursor as your default provider for dashboard or CLI chat. Cursor’s API is built for Cloud Agents, not chat completions. You will see an error if you try to chat with Cursor selected.

For chat, use OpenAI, Anthropic, Gemini, or Ollama.

Cursor integration is useful for IDE usage stats and agent-related features in Monitor, not for the chat panel.

Recommended setup

Connect at least one chat-capable provider.
In Settings → AI Preferences, set default provider and default model.
Choose a context strategy (e.g. debugging, architecture, code review) in the AI workspace.

API keys are sent only to the provider you connect; they are managed by your local gateway, not sent to LayrX servers.

Project workspace (`.layrx/`)

After layrx init, your project contains:

my-project/
├── .layrx/
│   ├── config.json      # Project config (agent port, paths)
│   ├── layrx.db         # Local SQLite index (created when agent starts)
│   ├── agent.json       # Agent process metadata (when started from this dir)
│   ├── agent.pid        # Agent PID file
│   ├── logs/
│   │   └── agent.log    # Gateway logs
│   └── cache/           # Local cache data
├── .git/
└── ... your source ...

`.gitignore` recommendation

Add local LayrX state to .gitignore unless your team intentionally shares it:

.layrx/

config.json can be committed if you want shared team defaults; the database and logs are usually kept local.

Working with multiple projects

Run layrx start once from a directory (creates .layrx/ there for agent metadata).
cd into each Git project and run layrx init to index that repo.
Switch the active repository in dashboard Settings → Repository, or run init from whichever project you are working in.

The gateway indexes repositories relative to where the agent was started and which repos you register via init.

Environment variables

The CLI sets these when starting the agent (you rarely need to set them manually):

Variable	Set by	Description
`GATEWAY_HOST`	`layrx start`	Bind host (default `127.0.0.1`)
`GATEWAY_PORT`	`layrx start`	HTTP port (default `8765`)
`DATABASE_PATH`	`layrx start`	Path to SQLite DB (default `.layrx/layrx.db`)
`REPOSITORY_PATH`	`layrx start`	Working directory when the agent was started

Updating

npm install -g layrx@latest
layrx restart

0.1.2 fixes init health verification, dashboard API routing (/api/*), and layrx dashboard reachability checks. Upgrade if you see init health failures or dashboard JSON parse errors.

If you upgraded from an older version and see missing gateway errors:

npm uninstall -g layrx
npm install -g layrx
layrx start

Uninstall

layrx stop
npm uninstall -g layrx

Remove per-project data if desired:

rm -rf .layrx

Troubleshooting

`LayrX Local Agent is not running` / `Agent unavailable`

Start the agent first:

layrx start
layrx status

`Current directory is not a Git repository`

Run layrx init from inside a folder with a .git directory, or run git init first.

`LayrX gateway is not installed`

Reinstall the global package:

npm install -g layrx

`npm install -g layrx` fails on `better-sqlite3` (Node.js 22+)

If you see a compile error like no member named 'GetPrototype' in 'v8::Object', your Node.js version is newer than the bundled native module supports.

Fix: Upgrade to the latest layrx (uses better-sqlite3 12+, which supports Node 20–26):

npm install -g layrx@latest

Or use an LTS Node version (20 or 22):

nvm install 22
nvm use 22
npm install -g layrx

On macOS, ensure Xcode Command Line Tools are installed if a native module must compile from source:

xcode-select --install

Port 8765 already in use

Start on another port:

layrx start --port 8766
layrx init --port 8766
layrx dashboard --port 8766

npm install -g layrx@latest
layrx restart
layrx dashboard

Ensure the agent is running and you are visiting the same host/port you started with (default http://127.0.0.1:8765). Check .layrx/logs/agent.log for errors.

`Agent health verification failed` after `layrx init`

Upgrade to 0.1.2+ and re-run init from your project directory:

cd /path/to/my-project
layrx init --force

Verbose debugging

Add --verbose to most commands, or inspect:

tail -f .layrx/logs/agent.log

Privacy and security

Repository indexing runs locally on your machine.
Source code is not uploaded to LayrX cloud services by the CLI or gateway.
AI providers receive only the prompts and context you send when you use chat; configure providers you trust.
API keys are stored locally by the gateway for the providers you connect.