Quickstart

🇬🇧 English · 🇮🇹 Italiano

_{Generated from README.md — edit that file in the repository, not this page.}

---

Get started

You need Git, Node.js and npm, plus access to an LLM backend. The package requires Node.js 18 or later; the project recommends 20 or later. TSUKA runs on Windows, Linux, and macOS.

1. Install from source

git clone https://github.com/nispa/tsuka.git
cd tsuka
npm install
npm run build
npm link

npm link makes the tsuka command available outside the repository.

2. Connect a model

For a local setup, start your backend and load a model with tool-calling support. The bundled Ollama configuration uses http://localhost:11434/v1 and qwen2.5-coder:7b.

If using Ollama, start ollama serve when the service is not already running. In a separate terminal, download the configured model:

ollama pull qwen2.5-coder:7b

For OpenRouter, add your key to a .env file in the directory where you will run TSUKA:

OPENROUTER_API_KEY=your_key_here

Launch TSUKA, then use /provider to select the backend and /models to select a model.

3. Open a workspace

Run TSUKA from the directory you want the agents to work in:

cd path/to/your/project
tsuka --tui

Use tsuka --cli for the line-based REPL. Running tsuka without a flag uses the configured defaultUi.

Start with a small request, such as “Read this project and explain its entry points.” Use /tools to inspect the available tools and /help for the commands supported by the current interface.

Configuration and customization

The installation directory is the default application home; TSUKA_HOME can override it. The working directory is the default workspace for file tools, unless workspaceRoot is configured.

File or directory	Purpose
.tsuka/config.json in the workspace, or tsuka.config.json in the application home as fallback	Active provider, model overrides, UI, execution limits, and optional features.
providers.json	Provider endpoints, default models, and API-key environment variable names.
.env	Credentials, loaded from the application home, then workspace .tsuka/.env, then workspace .env, with later files taking precedence.
characters/, roles/, traits/, teams/	Agent definitions and team compositions.

See the example configuration for available settings. Use /provider and /models to change the active backend interactively, and /benchmark to evaluate a model's tool-calling capabilities.

To create a project-local set of agent definitions, run one of these commands in the workspace:

tsuka init --preset core
tsuka init --preset full
tsuka init --preset core --pack osint,devops

These are alternative initializations. Running tsuka init alone opens the setup wizard. Local assets and configuration under .tsuka/ take precedence when present; otherwise the runtime falls back to the application home's tsuka.config.json.