Kodrik is a personal AI companion built in Rust. It supports broad conversations, remembers preferences, learns reusable procedures and explores interests. Programming is one of its abilities. Use it in a terminal, through Telegram or in the browser, with personal history, memory and skills shared across interfaces.
- Persistent memory, personality and searchable conversation history.
- Skills for reusable workflows, including skill creation and self-update.
- Saved conversations, automatic context compaction and agent-directed handoffs to existing or new dialogues when the topic changes.
- Image understanding from local files, Telegram photos and browser uploads; PDF, Office and text/code attachments in Telegram and web chat.
- Structured datasets for diaries and trackers, with queries and summaries.
- Tables, charts and interactive UI in browser chat; persistent public/private pages and dashboards, including private forms that save dataset records.
- Browser chat with streaming responses, tool details, cancellation, search, pinned dialogs and message editing that preserves previous conversation branches.
- Shared personal dialogs in Telegram and the browser, with a Telegram session picker and web sign-in through Telegram or the owner password.
- Optional remote TUI to the server agent with explicitly attached, temporary device files, shell, skills and HTTP MCP; access ends when TUI disconnects.
- Optional daily Telegram initiative based on saved interests and one-shot reminders.
- Optional web search through self-hosted SearXNG or DeGoog and page reading with local Obscura.
Images and documents are sent to the configured model provider for analysis. Images require a vision-capable model; documents require file-input support. PDF page images also require vision support.
Source repository: suinly/kodrik.
You need credentials for a model and endpoint supporting the OpenAI Responses API and tool calling. An endpoint that only supports Chat Completions is insufficient.
The Homebrew package currently targets macOS 14 Sonoma or newer on Apple Silicon. This is the package's chosen support floor; older macOS versions have not been validated. Intel Macs and Linux are not included in this release pipeline.
brew install suinly/tap/kodrik
kodrik --versionThe executable includes the web frontend and built-in skills. Rust, Node.js and a source checkout are not required. Installation does not create your configuration or start a background service. Continue with Configure and run below.
Source builds require a current stable Rust toolchain with Rust 2024 edition support, npm, and Node.js 22.22.3+ on 22.x, 24.15+ on 24.x, or 26+.
From the repository root, build the frontend before Rust; web assets are embedded in the executable, so no Node.js server is needed at runtime:
npm ci --prefix web
npm run build --prefix web
cargo build --release --locked
export PATH="$PWD/target/release:$PATH"The final command makes the built kodrik executable available in this shell.
You can also invoke ./target/release/kodrik directly from the checkout.
For either installation method, create the private state directory:
install -d -m 700 ~/.kodrikCreate ~/.kodrik/config.toml:
[gateway]
[provider.primary]
type = "openai"
model = "your-model"
api_key = "your-key"Replace the model and API key placeholders and run
chmod 600 ~/.kodrik/config.toml. The empty [gateway] table is
required even for terminal-only use. For a custom endpoint, set api_base under
[provider.primary]; see Configuration.
Launch the terminal UI or ask a single question:
kodrik
# Or ask a single question:
kodrik ask "What should we explore today?"Use /new for a fresh conversation and /sessions to reopen a saved one.
Multiple terminal UI instances keep independent session selections.
Launch from the directory where you want shell and file tools to work.
Use Ctrl+T to expand or collapse full received commands and tool results inline
in the conversation. The editor and normal chat scrolling remain available;
there is no separate viewer. Output omitted by the tool itself cannot be
restored; truncation markers and temporary-file paths remain visible.
Tool headers separate the device and completion status from the command.
Commands use a soft-blue $ line; output stays neutral, with an amber stderr
label. The compact view keeps the tail of both streams, and Ctrl+T reveals the
full received arguments and result.
To keep the agent and memory on a server instead, pair your device with
kodrik connect, then launch kodrik --remote. Local access starts detached and
requires /attach followed by /attach yes. See Remote TUI
for its separate configuration, data disclosure and cleanup limits; shell/MCP
are not sandboxed. There is no remote ask mode.
The web, TUI and Telegram interfaces support English and Russian. See Interface languages for detection and manual selection.
To enable Telegram, add a bot to ~/.kodrik/config.toml:
[gateway.telegram]
type = "telegram"
token = "your-bot-token"To enable browser chat and published pages locally, add:
[web]
enabled = true
listen = "127.0.0.1:8080"
base_url = "http://127.0.0.1:8080/"Set the owner password if using password login, then run the gateway:
kodrik web set-password
kodrik gatewayOpen the local chat and sign in with the owner password or through your configured Telegram bot. The gateway serves both Telegram and the enabled web interface; terminal mode does not start the server. For remote access, configure HTTPS following Web pages.
The owner can manage Bearer-authenticated webhooks from Webhooks in the chat
sidebar or ask the agent to manage them using its webhooks tool.
Each delivery starts a separate agent conversation using your saved
instruction. See Webhooks for request examples and limits.
The owner agent can use messages to send text to the owner's Telegram chat or
an existing/new web conversation, including when started by a webhook.
For a Homebrew installation, run the gateway in the background after configuration:
install -d -m 700 ~/.kodrik/workspace ~/.kodrik/logs
brew services start suinly/tap/kodrik
brew services info suinly/tap/kodrikStop the foreground gateway first. Run the service commands as your regular user,
without sudo. The background gateway works in ~/.kodrik/workspace and writes
logs to ~/.kodrik/logs/. If you previously used the source installer, follow
migration instructions
before starting the brew service.
Configuration and state live in ~/.kodrik/. Each user shares personal history,
memory and skills between Telegram and web; CLI/TUI always uses the configured
owner. Access requires an owner-issued invitation; groups are disabled. The owner
and invited users can invoke guest mode in private chats with other people. Each
pair shares guest history, memory, lists and sandboxed tools, separate from their
personal memory and files. The agent identifies each speaker by Telegram user ID.
Invited users use Bashkit with a persistent
virtual filesystem; CLI/TUI and the configured owner's personal chats retain
native shell and file tools. Set [owner] to link your Telegram identity to the
owner's state and native tools; without it, all Telegram chats use Bashkit.
Create a separate link for each person with kodrik invites create --label "Alice".
See invitations and Configuration.
With the build requirements above and a code-signing identity named Kodrik Local
available in your keychain, run ./scripts/install-macos.sh from the checkout.
The installer requires this identity and stops if signing fails. For a manual
build without service installation, use the commands above. Homebrew installations
use brew services instead; do not run this installer over a brew-managed service.
The installer builds and installs ~/.local/bin/kodrik, creates a configuration
template if needed, and manages the per-user gateway LaunchAgent. On a fresh
install, fill in ~/.kodrik/config.toml, configure Telegram and/or web, then rerun
the installer to start the gateway. Re-running installs the current checkout and
restarts the service. Logs live in ~/.kodrik/logs/. Add ~/.local/bin to your
shell's PATH for terminal use. See Operations.
Homebrew installations update with brew upgrade suinly/tap/kodrik. Finish active
conversations before restarting the service; see the
update procedure for preserving running
processes and verifying restart. Configuration and history remain in ~/.kodrik/
when the package is upgraded or uninstalled.
Homebrew release binaries use ad-hoc signing, without Apple notarization. Maintainers can follow GitHub setup and release steps: a version tag creates a tested draft release, publication opens a formula PR in the tap, and merging that PR makes the version available through Homebrew. Releases can also be built and verified locally before uploading their artifacts.
Start at the documentation index, or go directly to:
| Task | Guide |
|---|---|
| Install and launch | Getting started |
| Install with Homebrew or publish a release | Homebrew |
| Configure models or Telegram | Configuration |
| Find commands and shortcuts | Using Kodrik |
| Connect a device to the server agent | Remote TUI |
| Understand memory and learning | Memory · Companion |
| Manage sessions and context | Sessions |
| Create reusable workflows | Skills |
| Send photos or inspect screenshots | Images and vision |
| Keep diaries and structured records | Datasets |
| Create tables, charts and forms | UI documents |
| Publish pages and dashboards | Web pages |
| Chat in the browser | Web chat |
| Search the web and read links | Web research |
| Back up state or understand crash recovery | Storage · Durable recovery |
| Update or troubleshoot | Operations · Troubleshooting |
| Contribute to the code or documentation | Development · Documentation conventions |
Kodrik is licensed under the MIT License. Third-party components retain their respective licenses.