Installation
Tensaku is one gem in your development group. There is no JavaScript to set up.
After reading this page, you will know:
- What Tensaku needs.
- How to install it and check that it works.
- How to connect a coding agent.
- How to remove it.
Requirements
- Ruby 4.0 or later.
- Rails 8.1.
Bundler installs Herb and ReActionView with the gem. Tensaku works with importmap, jsbundling or no JavaScript at all, because its middleware injects one prebuilt script into HTML pages.
Install the gem
Add the gem to the development group:
bundle add tensaku --group development
Then restart your server. Editing and notes now work.
Check that it works
Open a page. A round button with a red flower sits in the bottom right corner. Press Alt Shift T for select mode and hover an element. The label shows the file and line it came from.
If the button doesn't appear
Tensaku only adds the overlay to full HTML pages with a 2xx or 422 status, requested from this machine. Check that:
- The server was restarted after the install and runs in development.
- The page's host is
localhost, a.localhostname, a loopback IP or a name inconfig.hosts. - The browser doesn't reach the server through a tunnel, a reverse proxy, Docker or a devcontainer.
- The response isn't streamed, compressed, sent from a file on disk or non-UTF-8.
Safety and limits has the details.
Connect a coding agent
The generator is optional. Run it to connect coding agents:
bin/rails generate tensaku:install
It prints every file it changes, and does this:
- Checks that Tensaku is in the development group, and warns if it isn't.
- Installs the skill in
.agents/skills/tensaku/, and for Claude Code in.claude/skills/tensaku/. - Adds
bundle exec tensaku mcp, the MCP server, to.mcp.json, and to the project config of each agent below that it sets up. - Adds
/tmp/tensaku/to.gitignoreunlesstmp/is already ignored. That folder holds the page token, the write lock, the MCP log and saved screenshots. Notes aren't kept in the project; see where notes live.
Each agent reads its own files:
| Agent | MCP entry | Skill | Checked |
|---|---|---|---|
| Claude Code | .mcp.json |
.claude/skills/tensaku/ |
Yes, Claude Code 2.1.323 |
| Codex | .codex/config.toml, read once you trust the project |
.agents/skills/tensaku/ |
No, from Codex's documentation |
| OpenCode | opencode.json |
.agents/skills/tensaku/ |
No, from OpenCode's documentation |
| Cursor | .cursor/mcp.json |
.agents/skills/tensaku/ |
No, from Cursor's documentation |
| Gemini CLI | .gemini/settings.json |
.agents/skills/tensaku/ |
No, from Gemini CLI's documentation |
| Copilot CLI, VS Code | .mcp.json |
.agents/skills/tensaku/ |
No, from GitHub's and VS Code's documentation |
.mcp.json and .agents/skills/tensaku/ are always written. The other files are written for the agents you name, or by default for those whose config directory or file is already in the project:
bin/rails generate tensaku:install --agents codex,cursor
bin/rails generate tensaku:install --agents all
The generator keeps the other servers in each JSON file, and appends to .codex/config.toml without rewriting it. It leaves opencode.jsonc alone and prints the entry to add by hand.
The .mcp.json entry looks like this:
{
"mcpServers": {
"tensaku": {
"command": "bundle",
"args": ["exec", "tensaku", "mcp"]
}
}
}
Every file the generator writes is in the project, so the MCP server and the skill load only for agents started in that project. Your agent starts the server itself, in the directory it runs in, and stops it when it quits. Claude Code asks you to approve a project's .mcp.json servers the first time. Restart the agent after running the generator. For another agent, add the same command to its MCP settings, or have it run bundle exec tensaku notes. See the MCP server.
Remove Tensaku
Run bundle remove tensaku, then delete what the generator and your notes left behind:
tmp/tensaku/- Your notes: the
tensakufolder in your user data folder (see where notes live) .claude/skills/tensaku/and.agents/skills/tensaku/- The
tensakuentry in.mcp.json,.codex/config.toml,.cursor/mcp.json,.gemini/settings.jsonandopencode.json - The
/tmp/tensaku/lines in.gitignore, if the generator added them config/initializers/tensaku.rb, if you made one