tiki

A Claude-Code-style coding agent, written in PHP on Laravel, with a browser UI.

Heads up: tiki is a personal project, not a polished product. It works and it's fun, but there are no support or stability guarantees. Expect rough edges.

What is tiki?

tiki is an agentic coding assistant you run locally. You launch it from a project directory, it opens a chat in your browser, and it reads, edits, and runs code in that project on your behalf — asking permission before anything risky.

Under the hood it's an explicit six-state machine persisted to SQLite, so closing the browser mid-turn is a no-op: reopen it and the turn resumes. The agent is strictly separated from the HTTP/SSE transport, and the LLM tool loop is driven by tiki itself (not by the underlying client), so every tool call passes through a single permission gate.

Highlights

• Six core tools — read_file, edit_file, write_file, bash, list_files, grep. edit_file does byte-exact matching with no fuzzy fallback (write atomically, verify-then-write).
• Plan & task tools plus an ask_user tool that lets the agent pause and ask you a clarifying question.
• Central permission gate — two axes (read/write/exec × inside/outside project root), with per-project persisted exceptions in .tiki/permissions.json and an absolute block list via .tikignore.
• Streaming chat UI — server-sent events, slash-command autocomplete, collapsible tool results, a plan sidebar, and an inline permission overlay.
• MCP client — connects to external Model Context Protocol servers (stdio), discovers their tools, and routes them through the same permission gate as native tools.
• Multi-provider — via Prism: Anthropic, OpenAI, Ollama, and any OpenAI-compatible endpoint (LM Studio, vLLM, llama.cpp, …), plus Mistral, Groq, xAI, Gemini, DeepSeek, OpenRouter and more. Switchable in-UI with /provider and /model.
• Project memory — TIKI.md (project) and ~/.config/tiki/TIKI.md (global) feed the system prompt; /init explores a repo and writes one for you.
• Cross-OS — runs natively on Windows and on WSL/Linux, with Windows↔WSL path translation so the same project opens from either side.

Requirements

• PHP 8.4+ (with the usual Laravel extensions) and Composer — that's it to run it.
• Node.js + npm — only needed for composer setup when running from source. The browser UI itself ships pre-built (vendored JS + inline CSS), so the global CLI install needs no build step.
• ripgrep (optional — grep falls back gracefully when it's absent).
• An LLM provider: an API key (Anthropic, OpenAI, …) or a local endpoint (Ollama, LM Studio, …).

No web server or database server required. tiki serves itself with PHP's built-in server (php artisan serve) and stores everything in a local SQLite file — there's no Apache/Nginx or MySQL to set up. On Windows, plain native PHP is enough; a full WAMP/XAMPP stack works too but only its PHP is actually used.

Install (global CLI)

tiki isn't on Packagist (yet), so install it straight from this GitHub repo. Register it as a global VCS repository once, then require the package — note the package name is rnkr69/tiki, even though the repo is tiki-code:

composer global config repositories.tiki vcs https://github.com/rnkr69/tiki-code.git
composer global require rnkr69/tiki:@dev

Once it's published to Packagist, the first command goes away and a plain composer global require rnkr69/tiki is enough.

Then, from the root of any project you want to work on:

tiki

tiki captures your current directory as the project root, picks a free port starting at 7100, opens your browser, and starts the agent. The first run walks you through a short wizard to pick a provider and model.

Run from source / Development

git clone https://github.com/rnkr69/tiki-code.git
cd tiki-code

composer setup     # install deps, create .env, generate key, migrate, build assets
composer dev       # server (port 8050) + queue + log tail + vite, all at once

Other useful commands:

composer test                                   # run the test suite
php artisan test --filter=AgentTest             # run a single test class
./vendor/bin/pint                               # format (Laravel Pint, project standard)

The dev database is SQLite at database/database.sqlite; queue, cache, and sessions are all database-backed.

Configuration

LLM provider settings come from environment variables — copy .env.example to .env and fill in only the provider you use (API key, or base URL for a local endpoint). See the commented tiki section at the bottom of .env.example.

• TIKI_LLM_TIMEOUT (default 120 seconds) governs the per-request timeout — raise it for slow local models.
• The active provider/model is stored in storage/framework/tiki-runtime.json (gitignored) and can be changed in-chat with /provider and /model.
• Per-project permission exceptions live in .tiki/permissions.json; secrets and machine-specific paths can be hard-blocked via .tikignore.
• To wire up MCP servers, create ~/.config/tiki/mcp.json (global) or <project>/.tiki/mcp.json (project) using the Claude Desktop mcpServers shape, then run /mcp in the chat.

Status

• v0.1 — agent loop, six-state machine, all core tools, permission gate, streaming chat UI, slash commands, history compaction. ✅ Working.
• v0.1.1 — .tikignore absolute block list, output caps for local LLMs, Windows↔WSL path translation.
• v0.2 — MCP client (stdio transport): discover and route external MCP tools through the permission gate.

Design

The full v0.1 design document — every architectural decision with its reasoning and its rejected alternatives — lives in docs/ARCHITECTURE.md (Spanish). It covers why Prism is used as a streaming client rather than the tool-loop orchestrator, why the agent loop is modelled as an explicit state machine, how the permission gate combines its two axes, and the context-management strategy. If you want the "why" behind the code, start there.

Contributing

PRs and issues are welcome, with the caveat above that this is a personal project. See CONTRIBUTING.md.

License

MIT.