UIntellAgent documentation

Installation

Install and start

Install the stable Linux x86-64 release with one command, configure a provider, and start the unified TUI.

curl --proto '=https' --tlsv1.2 -fsSL https://uintell.org/install.sh | sh

The bootstrap is pinned to the v1.0.2 release checksum and installs without sudo into ~/.local/bin. Read the installer before running it when your shell policy does not allow piped scripts.

Manual verified release

version=1.0.2
asset="uintell-agent-${version}-x86_64-unknown-linux-gnu"
base_url="https://github.com/uintell/uintellagent/releases/download/v${version}"

curl --fail --location --remote-name "${base_url}/${asset}.tar.gz"
curl --fail --location --remote-name "${base_url}/SHA256SUMS"
sha256sum --ignore-missing --check SHA256SUMS
tar -xzf "${asset}.tar.gz"
cd "$asset"
./install.sh
export PATH="$HOME/.local/bin:$PATH"
export DEEPSEEK_API_KEY="sk-..."
uintell-agent doctor
uintell-agent --tui

Fish shell and private prompt history

The v1.0.2 installer includes native Fish completions and the ua launcher under ~/.config/fish. In the TUI, Up/Down recalls project-scoped prompts and Tab or Right accepts the visible suggestion. Inputs resembling credentials, private keys, recovery phrases, or Nostr secret keys are not persisted.

ua
ua explain this Rust borrow error
uintell-agent history list --limit 50
uintell-agent history clear

The default provider reads DEEPSEEK_API_KEY. At startup, the unified TUI checks provider health, starts local SurrealDB when required, initializes its schema, and restores workspace state from ~/.uintell/workspace.json.

Build from source

Use Rust 1.94 or newer to build the same version from the public repository.

git clone https://github.com/uintell/uintellagent.git
cd uintellagent
git checkout v1.0.2
export DEEPSEEK_API_KEY="sk-..."
cargo run -- doctor
cargo run -- --tui

Use Ollama

Start Ollama first, then select it with the global --ollama flag.

ollama serve
~/.local/bin/uintell-agent --ollama --tui

Override the default Ollama model with --model <name>. The same tools, graph memory, editor, and run engine remain available with either provider.

Optimized source build

cargo build --release --locked
./target/release/uintell-agent --tui

Environment doctor

Verify the runtime before starting work

doctor checks the dependencies that UIntellAgent actually advertises and uses.

cargo run -- doctor

Configuration

Environment variables and persisted state

Local state

Unified TUI

Five persistent workspaces

Start the interface with cargo run -- --tui. Switch workspaces globally without destroying their state.

The active workspace, open editor location, selected run, and graph view are restored the next time the TUI starts.

Chat workspace

Stream, intervene, and start durable work

Chat streams model output and tool events in one timeline. Use Alt+Enter to send andEsc or Ctrl+G to cancel an active model/tool run.

Graph memory

Build durable knowledge from nodes and directed relations

A node is one persistent, self-contained fact stored in SurrealDB. Nodes survive agent restarts and can be searched, edited, grouped into datasets, connected to other facts, or loaded into a future model turn. Open Memory with Alt+2. Inside Memory, plain keys 1 through 4 switch Graph, Explorer, Query, and Analytics.

What a knowledge node stores

Create your first node

1. Press Alt+2 to open Memory, then press plain 2 for Explorer.
2. Press c to open the Create Knowledge Unit form.
3. Use Tab and Shift+Tab to move between fields. Content cannot be empty.
4. Press Enter to validate and save. Read the bottom status line if the form remains open.

Type:       decision
Content:    UIntellAgent v1.1 will use a provider registry.
Dataset:    uintellagent
Tags:       providers,v1.1
Confidence: 1.0

Connect two nodes

Relations are directed: the node selected first is the source and the node selected second is the target. Use Explorer for the clearest selection workflow.

1. Press plain 2 for Explorer and select the source node with j/k.
2. Optionally press t to choose relates_to or proves.
3. Press lowercase l once. The status line reports link source ...; select target and press l.
4. Select a different target node with j/k.
5. Press lowercase l again to persist source --relation--> target.
6. Press plain 1 for Graph. Use a for layout or Z to fit all visible nodes.

Esc cancels a pending link. Selecting the same node as source and target also cancels it. If a dataset or type filter hides one endpoint, switch the filter before linking.

Choose the correct relation

[finding] All provider-registry tests passed
    --proves-->
[decision] The provider registry is ready to ship

[error] A node with empty content cannot be saved
    --relates_to-->
[fix] Add required content before pressing Enter

Inspect, arrange, and remove connections

Let the agent store and recall knowledge

In Chat, ask the agent to remember a durable fact or recall a previous decision. The same operations are available explicitly in Tools through graph_store, graph_query,graph_context, graph_edit, and graph_forget.

:run graph_store {"fact_type":"decision","content":"Use a provider registry in v1.1","dataset":"uintellagent","tags":["providers","v1.1"],"confidence":1.0}
:run graph_query {"query":"provider registry","limit":10}
:run graph_context {"fact_types":["decision"],"limit":20}

• graph_store creates a fact; graph_query searches fact content and returns record IDs.
• graph_context loads high-confidence, recent facts into model context.
• graph_edit updates a record ID returned by a query.
• graph_forget permanently deletes a fact and is not the same as the TUI's undoable workflow.

SurrealQL and graph commands

:query SELECT * FROM fact LIMIT 20;
:dataset code
:layout
:fit-all
:view-save code-review
:export ~/.uintell/graph-snapshot.json
:repair

:query accepts read-only SurrealQL. Mutations require :query!, then an additional preview and confirmation. Imports are validated before :import! can merge new records.

Scale and recovery

• :load-more [count] and :load-all raise the interactive window up to 100,000 nodes.
• :view-save, :view, and :views persist filters, pan, and zoom.
• :export writes a versioned JSON snapshot; :repair fixes metadata and duplicate edges.
• Refresh, layout, and query operations run as cancellable background jobs with retry support.

Tools workspace

Inspect and execute the registered catalog

Select tools with j/k. Enter prepares a call. Use :run for a normal policy check and :run! only to explicitly confirm a call that requested confirmation.

:run file_read {"path":"Cargo.toml","limit":40}
:run! code_exec {"language":"python","code":"print(2 + 2)"}

Editor workspace

Edit real files with code intelligence and review gates

The Vim-style editor combines a project tree, text buffer, diagnostics, completions, definitions, agent change review, and a run inspector. Agent file_write calls never silently replace an unsaved buffer.

Editor commands

Durable runs

Checkpoint autonomous coding work

A run inspects and plans, implements against real files, verifies, performs an independent review, repairs failed quality gates within bounds, and writes a final engineering report.

~/.local/bin/uintell-agent task start "implement the requested change and verify it"
~/.local/bin/uintell-agent task start --remember "implement and remember the decision"
~/.local/bin/uintell-agent task list
~/.local/bin/uintell-agent task show <run-id>
~/.local/bin/uintell-agent task resume <run-id>

• Start in Chat with /task <objective> or in Runs with :new <objective>.
• Use --remember only when the run may persist or mutate graph knowledge.
• c or Ctrl+G cancels at a checkpoint; r resumes eligible runs.
• Completed tool calls are recorded in a result ledger and are not replayed after interruption.
• Only one process can drive a run at a time.

CLI reference

Commands and global flags

Global flags

cargo run -- --help
cargo run -- task --help
cargo run -- serve --help

HTTP gateway

Run UIntellAgent as an authenticated local service

export DEEPSEEK_API_KEY="sk-..."
export UINTELL_API_KEY="replace-with-a-separate-secret"
~/.local/bin/uintell-agent serve --addr 127.0.0.1:3000

curl http://127.0.0.1:3000/chat \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: replace-with-a-separate-secret' \
  -H 'X-Request-Id: example-001' \
  -d '{"message":"Inspect this task","session_id":"docs-demo"}'

Gateway limits

• Authenticate with X-API-Key or Authorization: Bearer.
• 60 requests per minute per API key.
• 120-second model timeout.
• 32,000 characters per message and 128 characters per session ID.
• X-Request-Id is accepted or generated automatically.

Permissions

Put policy between model intent and side effects

The file ~/.uintell/permissions.toml is created with workspace-safe defaults when absent.

config_version = 1
mode = "workspace"
workspace_dirs = ["."]
allowed_commands = ["ls", "cat", "head", "tail", "rg", "git", "cargo", "code_exec", "npm", "pnpm"]
denied_commands = ["rm -rf /", "dd if=", "mkfs", "shutdown", "reboot", "halt", "poweroff"]
allowed_read_paths = ["/tmp"]
denied_read_paths = ["/etc/shadow", ".ssh", ".aws", ".gnupg", ".kube", ".docker", ".env*", ".netrc", "*.pem", "*.key"]
allowed_write_paths = ["/tmp"]
denied_write_paths = ["/etc", "/boot", "/sys", "/proc", "/dev"]
allowed_hosts = ["api.deepseek.com", "127.0.0.1", "localhost", "duckduckgo.com", "crates.io", "github.com", "raw.githubusercontent.com", "openrouter.ai"]
denied_hosts = []
confirm_destructive = true

Deny rules are evaluated before allow rules. Shell expansion, redirection, interpreters, repository code, and filesystem inspection require confirmation even when a command name appears in the allow list.

Skills

Create and select instruction skills

uintell-agent skill-new release-notes "Generate verified release notes"
$EDITOR "$HOME/.uintell/skills/release-notes/SKILL.md"
uintell-agent --skill release-notes --tui
uintell-agent skills

Each skill stores a format-versioned skill.toml and bounded Markdown instructions. Select up to eight skills explicitly with repeated --skill <name> flags; selected instructions are composed into the agent preamble before execution.

Troubleshooting

Diagnose common failures

Provider returns 401 Unauthorized

Replace DEEPSEEK_API_KEY, restart UIntellAgent, and run cargo run -- doctor. Use --ollama when no cloud key should be required.

Graph context reports an error

With the default local URL, the agent starts SurrealDB automatically. Confirm the surreal binary is installed, inspect ~/.uintell/surrealdb.log, and verify UINTELL_DB_URL. SetUINTELL_DB_AUTOSTART=0 only when another service manager owns the database.

Tool confirmation dialog appears

The call did not match an unconditional allow rule or was classified as destructive. Review the exact tool and arguments. Approve through the TUI or repeat a prepared Tools call with :run!. Denied calls cannot be confirmed.

code_exec cannot find a temporary source file

Run the doctor and verify that the language runtime, temporary directory, and Bubblewrap are available and writable.

Editor completion is unavailable

Install rust-analyzer or set UINTELL_LSP_COMMAND and UINTELL_LSP_ARGS for a custom server. The default Rust server intentionally ignores unsupported file types such as TOML.

A run is paused after a crash

Open Runs and resume it, or use cargo run -- task resume <run-id>. Completed ledger entries are not replayed.

cargo run -- doctor
cargo run -- task list
cargo run -- task show <run-id>