# TiTools - Titanium CLI for AI coding assistants
<div align="center">
  
</div>
TiTools is a Titanium SDK toolkit for AI coding assistants. It ships 13 skills — 8 specialist skills (`ti-reuse-first`, `ti-expert`, `purgetss`, `ti-ui`, `ti-game`, `ti-game-assets`, `ti-synthengine`, `ti-admob-unified`) plus 5 documentation-mirror skills (`ti-api`, `ti-guides`, `ti-howtos`, `alloy-guides`, `alloy-howtos`) — a research agent, and reference files covering reuse and simplification, Titanium architecture, API reference, native how-tos, Alloy MVC, PurgeTSS styling and resource automation, UI/UX patterns, 2D games, and native sound synthesis.
The reference files are maintained against official documentation whenever an official source exists, so the assistant can retrieve current framework behavior instead of guessing from generic training data. As of v5.0.0 those sources are the Titanium SDK's own API definitions and the rewritten guides at [titaniumsdk.com](https://titaniumsdk.com). [Where the references come from](#where-the-references-come-from) has the detail.
Without TiTools, assistants rely on general training data. That data can be outdated or too generic for Titanium work. With TiTools, the assistant can look up Alloy architecture, memory cleanup patterns, PurgeTSS utility classes, and platform-specific APIs.
The optional knowledge index helps assistants discover the installed reference documents. See [skills and the knowledge index](docs/knowledge-index.md).
---
## Safety and disclaimer
TiTools installs documentation skills and a research agent into your AI coding assistant's skill directories and, when you run `titools sync`, injects a knowledge index block into your project's `AGENTS.md`/`CLAUDE.md`/`GEMINI.md`.
The maintainers of TiTools accept no responsibility for data loss, build breakage, or any other damage caused by the use of the CLI, skills, or the AI assistant's code suggestions. The tool is provided AS IS under the MIT License — see [`LICENSE`](./LICENSE) for the full terms. Use at your own risk.
---
## Installation
### Option A: Plugin Marketplace (Claude Code only)
The fastest way to get started with Claude Code. One command to add the marketplace, one to install:
```bash
/plugin marketplace add macCesar/titools
/plugin install titools@maccesar-titools
```
What you get:
- All 13 TiTools skills (`ti-reuse-first`, `ti-expert`, `purgetss`, `ti-ui`, `ti-game`, `ti-game-assets`, `ti-synthengine`, `ti-admob-unified`, `ti-api`, `ti-guides`, `ti-howtos`, `alloy-guides`, `alloy-howtos`)
- ti-pro research agent
- Session hook that auto-detects Titanium projects (`tiapp.xml`, Alloy, PurgeTSS, `ti.game`, `ti.synthengine`)
- Slash commands: `/ti-check`, `/ti-new-screen`, `/ti-audit`
- Auto-updates via marketplace (opt-in — see note below)
> **Note on auto-updates:** Claude Code disables auto-updates by default for third-party marketplaces like this one. To receive new versions automatically, open `/plugin` → **Marketplaces** tab and enable auto-update for `maccesar-titools`. When an update is applied, Claude Code prompts you to run `/reload-plugins` to activate the new code.
### Option B: CLI (Claude Code, Gemini CLI, Codex CLI)
Cross-platform installation via npm. Works with all three AI coding assistants:
```bash
# 1) Install the CLI
npm install -g @maccesar/titools
# 2) Install skills globally
titools install
# 3) Go to your Titanium project
cd /path/to/your/project
# 4) Sync the knowledge index into your project files
titools sync
# 5) Start your AI coding assistant
claude # or gemini, or codex
# 6) Ask away!
# "How should I structure a new app with login, signup, and a dashboard?"
# "My ListView with 500 items scrolls poorly on Android. How do I fix it?"
```
What gets installed:
- The 13 TiTools skills to `~/.agents/skills/`
- ti-pro agent for Claude Code
- Platform symlinks for Claude Code (Gemini CLI and Codex CLI auto-discover from `~/.agents/skills/` — no symlinks needed)
- Knowledge index in your project's `AGENTS.md`/`CLAUDE.md`/`GEMINI.md`
- Claude Code SessionStart hook for auto-updates
Why NPM?
- Cross-platform (macOS, Linux, Windows)
- No sudo required
- Auto-updates via Claude Code hook (checks once per day)
### Which option should I use?
| | Plugin (Option A) | CLI (Option B) |
| ------------------- | ------------------------------------------------------------------------------------- | ---------------------------------- |
| **Claude Code** | Recommended | Supported |
| **Gemini CLI** | Not available | Supported |
| **Codex CLI** | Not available | Supported |
| **Knowledge Index** | Not included | Included (`titools sync`) |
| **Auto-updates** | Marketplace (opt-in, enable in `/plugin`) | SessionStart hook (daily) |
| **Slash commands** | `/ti-check`, `/ti-new-screen`, `/ti-audit` | Same three (`~/.claude/commands/`) |
| **Session hook** | Auto-detects Titanium projects (Alloy/Classic, PurgeTSS, `ti.game`, `ti.synthengine`) | Auto-update only |
Having both installed is fine: the CLI detects an enabled marketplace plugin and skips its own skill symlinks and command copies, so nothing shows up twice. `titools doctor` reports which channel is serving Claude Code.
Use **Option A** if you only use Claude Code. Use **Option B** if you use multiple AI assistants or want the Knowledge Index feature.
---
## Compatible platforms
| Platform | Status | Skills Path |
| --------------------------------------------------------- | ---------------- | ------------------------------------- |
| [Claude Code](https://claude.ai/claude-code) | Fully Compatible | `~/.claude/skills/` (symlinked) |
| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | Fully Compatible | `~/.agents/skills/` (auto-discovered) |
| [Codex CLI](https://developers.openai.com/codex/cli/) | Fully Compatible | `~/.agents/skills/` (auto-discovered) |
All three platforms use the Agent Skills open standard: a `SKILL.md` file with YAML frontmatter. Gemini CLI and Codex CLI auto-discover skills from `~/.agents/skills/` per [agentskills.io](https://agentskills.io), so TiTools does not create redundant platform-specific symlinks for them.
---
## Knowledge index
The knowledge index is a compressed documentation map that gets injected into your project's instruction files. It tells the AI where Titanium reference docs are, so it can pull accurate information from the installed references instead of relying on general training data.
### Reference discovery
Skills provide task-specific workflows; the knowledge index makes their reference
locations discoverable from your project's instruction files. Load the relevant
references before relying on an API, platform requirement or module contract.
See [how the index works](docs/knowledge-index.md).
### What gets generated
The `titools sync` command generates a block like this inside your project files:
```
[Titanium SDK Docs Index]|root: ~/.agents/skills
|MANDATORY: Your training data for Titanium SDK, Alloy, and PurgeTSS is OUTDATED and INCOMPLETE. These reference files are the SINGLE SOURCE OF TRUTH. Prefer retrieval-led reasoning over pre-training-led reasoning. ALWAYS read the relevant files below BEFORE writing any code.
|ti-expert/references:{alloy-structure.md,anti-patterns.md,...}
|purgetss/references:{animation-system.md,class-index.md,...}
|ti-ui/references:{layouts-and-positioning.md,listviews-and-performance.md,...}
...
```
Note: The index is injected as direct content (no code blocks) so the model treats it as an active instruction, not illustrative text.
File selection per assistant:
- Claude Code -> `CLAUDE.md`
- Gemini CLI -> `GEMINI.md`
- Codex CLI / others -> `AGENTS.md`
### How skills and the knowledge index work together
The knowledge index provides always-available context (the documentation map). Skills provide specialized, on-demand expertise (the actual knowledge).
Together they work like this:
| Your Question | Knowledge Index Provides | Skills Activate |
| ------------------------------- | ------------------------------- | ---------------------------- |
| "Create a login screen" | Context about project structure | `ti-expert`, `ti-ui` |
| "Optimize ListView performance" | Points to docs location | `ti-ui` reads specific files |
| "Implement push notifications" | API reference paths | `ti-expert`, `ti-howtos` |
You do not need to explicitly invoke skills. The AI detects when to use them based on your question.
### Version notice
The knowledge index is based on the latest Titanium SDK documentation. If your project uses an older version, the command will warn you about potential API differences.
---
## Skills overview
| Skill | Purpose | Best For |
| ---------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ti-reuse-first | Reuse before writing new code | Whether it should exist and what already does it; duplication sweeps |
| ti-expert | Architecture and implementation | Starting point for most tasks |
| purgetss | Alloy styling + asset automation | Utility classes; Alloy/Classic branding, images, colors, fonts and modules |
| ti-ui | UI/UX patterns | Complex layouts, ListViews, platform UI |
| ti-game | 2D games with the `ti.game` module | Sprites, physics, tile maps, HUDs, camera, focused keyboard/mouse/gamepad actions, Apple Metal/Catalyst |
| ti-game-assets | Visual and sound assets | Image generation/editing, synthesis variants, stereo placement, alpha cleanup, manifests, parallax and complete exports |
| ti-synthengine | Sound design with `ti.synthengine` | Tones, chords, retro/UI effects, alarms, sweeps, patterns, ADSR envelopes, resonant filters, FM, detune, binaural positioning, held voices, native sequences, master effects, voice LFOs, engine statistics, bounded attack variation, seeds, instrument/effect fidelity, mixing and troubleshooting |
| ti-admob-unified | Advertising, privacy and mediation | Official `ti.admob.unified` guides, copy-ready library, banners/fullscreen, UMP/ATT and selected-provider configuration |
| ti-api | Complete Titanium API reference | Looking up properties, methods, events |
| ti-guides | SDK fundamentals | tiapp.xml, Hyperloop, distribution, JDK/Xcode compatibility, release notes |
| ti-howtos | Native feature integration | Location, push, media, platform APIs |
| alloy-guides | Alloy MVC framework reference | Controllers, models, views, widgets |
| alloy-howtos | Alloy CLI, configuration, debugging | alloy.jmk, config.json, custom XML tags |
Notes:
- The first eight (`ti-reuse-first`, `ti-expert`, `purgetss`, `ti-ui`, `ti-game`, `ti-game-assets`, `ti-synthengine`, `ti-admob-unified`) are specialist workflow skills reflecting TiTools' Titanium conventions and native-module contracts.
- `ti-reuse-first` runs before the others. It asks whether a thing needs to exist and what already does it — a search order that stops at the first rung that holds — and sweeps an existing `app/` for near-identical controllers, single-listener events, wrappers around one call, and layout recomputed in JavaScript. It is deliberately two-sided: it says when adding a module or a Widget is the right answer, so the bias does not simply invert.
- `ti-game` documents the `ti.game` native module (2D sprite engine using OpenGL ES 2.0 on Android and Metal on iPhone, iPad and Mac Catalyst). Its API reference was verified against the module source and records the reviewed upstream commit and fork documentation snapshot; it applies to Alloy and Classic projects alike and does not depend on PurgeTSS.
- `ti-synthengine` translates sound requests into checked JavaScript for published Android/iOS `ti.synthengine` 1.0.2 and local 1.1.0 candidates (public API 1.0.0). Its nineteen-method contract covers timed/held voices, identified native sequences, global tempo, selective categories/sends, master effects, live spatial/noise/filter controls and diagnostics. Two curated recipe guides cover retro cues and interactive instruments. Complete official-source mirrors, validation reports, bundled examples and raw evidence retain provenance; verified corrections are applied to official source prose before mirroring. The reviewed source commit/worktree, platform differences and scoped listening/performance acceptance are explicit in source notes.
- `ti-game-assets` treats images and sounds as essential game assets. It coordinates integrated `image_gen` artwork with `ti-synthengine` sound design, variants and stereo placement, and ships Pillow helpers for conservative alpha cleanup and per-world visual/audio manifests.
- The latter five are documentation-mirror skills, audited against official sources via the internal `titools-skill-auditor`. See [Where the references come from](#where-the-references-come-from).
- `purgetss` reference files are audited against the official PurgeTSS documentation and against the package source (the CLI and the generated `utilities.tss`), but its workflow conventions are opinionated.
---
## Where the references come from
The Titanium documentation was rewritten during 2026, and v5.0.0 moved TiTools onto the new sources. No skill, command or flag was renamed and the references answer the same questions. What changed is what they are checked against.
| Source | Feeds | Why it is the one |
| ------------------------------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| [`tidev/titanium-sdk`](https://github.com/tidev/titanium-sdk) → `apidoc/*.yml` | `ti-api` | The API definitions the SDK team edits. Every other copy of the API is compiled from these. |
| [`tidev/titaniumsdk.com`](https://github.com/tidev/titaniumsdk.com) → `content/docs/` | `ti-guides`, `ti-howtos`, `alloy-guides`, `alloy-howtos` | The rewritten guides, and what [titaniumsdk.com](https://titaniumsdk.com) serves. |
| `tidev/titaniumsdk.com` → `registry/sdk/<version>/` | `ti-api`, as a cross-check | The API compiled per published release. It answers which version actually shipped an API, which the YAML alone cannot. |
| [`tidev/titanium-docs`](https://github.com/tidev/titanium-docs) | all five, as an archive | The previous corpus, now frozen. Kept for what the rewrite left out. |
### Why the API comes from the SDK
The website does not write API documentation. It compiles it from `apidoc/*.yml` and commits the result, so it trails the SDK by construction. `ti-api` reads the YAML for what exists and the compiled registry for which release shipped it, and documents the newest GA rather than `main`. An API merged into the SDK today reaches these references when the release carrying it ships, because until then you cannot call it.
### The archive is additive
`tidev/titanium-docs` is frozen and being archived upstream. TiDev's own migration audit classifies its 336 guide pages as 121 rewritten, 121 merged, 2 kept and 92 archived. Of those 92, 91 are release notes and the last is the discontinued Atom package, so no guide topic was dropped. The difference is density: 1390 KB of legacy prose became 219 KB.
TiTools keeps the full corpus. The archive never overrides a live source on a question of fact, and nothing is deleted from a reference merely because the rewritten site no longer covers it. These skills still answer questions the official guides have not been rewritten to cover yet, such as the conditional `if=` attribute in Alloy XML and TSS, custom XML tags via `app/lib/`, and `alloy compile`.
---
## Agents (Claude Code only)
In addition to skills, this repository includes sub-agents for Claude Code. Sub-agents run in isolated contexts and are useful for research tasks that produce verbose output.
### ti-pro
Deep-dive research specialist that can combine the complete 13-skill TiTools catalog.
| Aspect | Details |
| ---------------- | ------------------------------------------- |
| Location | `~/.claude/agents/ti-pro.md` |
| Model | Sonnet (comprehensive analysis) |
| Tools | Read, Grep, Glob, Bash |
| Preloaded Skills | All 13 skills registered in `lib/config.js` |
When to use the agent vs skills:
| Use Case | Use This | Why |
| ---------------------------- | ------------------------------- | ---------------------------------------------------- |
| Quick inline reference | `/ti-expert`, `/purgetss`, etc. | Runs in main conversation, interactive |
| Analyzing an entire codebase | `ti-pro` agent | Isolates verbose output, cross-references all skills |
| Multi-feature research | `ti-pro` agent | Preloads all skills for comprehensive answers |
| Step-by-step implementation | Skills directly | Task-oriented guidance |
| Architecture review | `ti-pro` agent | Read-only analysis across all documentation |
Example prompts for the agent:
```
"Can you use the ti-pro agent to analyze this Alloy codebase's architecture?"
"Can you research how to combine location, push, and background sync in Titanium?"
"Can you compare ListView vs TableView performance for my use case?"
"Review this Titanium mobile app and identify anti-patterns."
```
Tip: For automatic activation, include words like "Titanium", "Alloy", or "mobile app" in your prompt to ensure the specialized agent is used instead of generic code analysis.
Key difference:
- Skills = interactive help during development (inline, conversational)
- Agents = isolated research tasks (returns summary, keeps verbose output separate)
---
## Slash Commands (Claude Code)
TiTools provides slash commands for common tasks. Both channels ship them: the plugin serves them from its own cache, and `titools install` copies them into `~/.claude/commands/`. If you have both, the CLI detects the plugin and skips its own copy so the command does not appear twice in the autocomplete.
| Command | Description |
| ----------------------- | ----------------------------------------------------------------------------------- |
| `/ti-check` | Verify project setup: SDK version, Alloy structure, PurgeTSS config, common issues |
| `/ti-new-screen <name>` | Create a new Alloy screen (controller + view + style) following project conventions |
| `/ti-audit` | Audit project for anti-patterns, memory leaks, and best practice violations |
These commands automatically invoke the relevant skills:
- `/ti-check` reads `tiapp.xml`, validates declared native modules, and reports project health
- `/ti-new-screen` uses `ti-expert` + `purgetss` to create properly structured files
- `/ti-audit` routes all 13 skills: the reuse sweep first, core Titanium checks always, Alloy/PurgeTSS checks when detected, integration how-tos when used, `ti-game-assets` checks for game asset workflows, and `ti-game` / `ti-synthengine` / `ti-admob-unified` checks when those modules are declared
---
## Session Hook (Plugin only)
The plugin includes a session start hook that auto-detects Titanium projects. When you open Claude Code in a directory with `tiapp.xml`, it automatically reports:
```
Titanium Alloy + PurgeTSS + ti.game + ti.synthengine project detected. TiTools skills are available and MUST be used...
```
It reports Alloy vs Classic, whether PurgeTSS is configured, and whether the project declares `ti.game` or `ti.synthengine`. Each detected native module adds a direct reminder to load its dedicated skill before writing module code.
This ensures Claude knows it's a Titanium project from the first prompt, preventing it from writing generic code.
---
## How skills work
Skills are automatically activated based on your questions. Just ask naturally:
```
"Can you create a login screen with email validation and animations?"
```
The AI will automatically use:
- `ti-expert` -> Architecture and controller structure
- `purgetss` -> Alloy styling, or supported asset/CommonJS commands in Alloy and Classic (if PurgeTSS is detected or requested)
- `ti-howtos` -> Secure token storage and native integration guidance
You do not need to call skills explicitly. The AI reads skill descriptions and loads the appropriate knowledge when needed.
### Project detection
All skills include automatic project detection to ensure compatibility:
| Skill | What It Detects | How It Works |
| ---------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| purgetss | PurgeTSS mode and project type | Checks PurgeTSS markers, then separates Alloy utilities from Classic standalone commands |
| ti-reuse-first | Existing app structure | Searches `app/lib/`, `app/controllers/`, `app/widgets/`, `purgetss/config.cjs` before proposing anything new |
| ti-expert | Alloy vs Classic | Checks for `app/` (Alloy) vs `Resources/` (Classic) structure |
| ti-ui | Titanium projects | Checks for `tiapp.xml` (both Alloy and Classic) |
| ti-game | ti.game module | Checks for `<module>ti.game</module>` in `tiapp.xml` or `require('ti.game')` |
| ti-game-assets | Game art/sound workflows | Reads asset inventories, generation/export workflows and requested visual or sound assets; no module install required for drawings |
| ti-admob-unified | ti.admob.unified and mediation | Declared core/complement modules or requested ad/privacy/provider integration |
| ti-synthengine | ti.synthengine module | Checks for `<module>ti.synthengine</module>` in `tiapp.xml` or `require('ti.synthengine')` |
Why this matters:
- PurgeTSS suggestions are provided when its project markers are detected or the user explicitly requests a standalone command
- Alloy-specific patterns are only suggested for Alloy projects
- Classic Titanium projects will not receive inappropriate Alloy advice
### Skill hierarchy
`ti-reuse-first` runs first — it decides whether there is anything to build — and `ti-expert` is the architectural starting point for what survives that question. Together they coordinate the rest of the bundled catalog:
| Scope | Skills |
| -------------------------- | --------------------------------------------------------------------------- |
| Whether to build it at all | `ti-reuse-first`, first |
| Architecture and UI | `ti-expert`, `ti-ui`, `purgetss` when configured |
| Game assets | `ti-game-assets` for visual and sound creation, preparation and integration |
| Native modules | `ti-game`, `ti-synthengine`, `ti-admob-unified` when declared or requested |
| Exact SDK/API guidance | `ti-api`, `ti-guides`, `ti-howtos` |
| Alloy MVC and tooling | `alloy-guides`, `alloy-howtos` for Alloy projects |
All thirteen ship with TiTools; no second skill package is required.
---
## Skill details
### ti-expert
The primary skill for Titanium Alloy development. Start here for most tasks.
When it activates:
- Designing project structure
- Implementing controllers, views, services
- Choosing data strategies (Models vs Collections)
- Writing clean ES6+ code
- Memory management and cleanup patterns
- Choosing a feedback surface (Snackbar, Dialog, Bottom Sheet) and deciding what stays native
- Designing reusable Alloy Widgets and their lifecycle contracts
- Adaptive layouts for tablets, foldables, and large screens
- Associating a custom file type with the app so tapping a document opens it
- Sharing a link or a file out through the iOS share sheet or the Android intent chooser
- Theming and dark mode
- Performance optimization
- Security patterns
- Migrating legacy apps
Example prompts:
```
"How should I structure a new Titanium Alloy app with authentication?"
"Create a user service that fetches data from an API."
"What's the best pattern for navigation between screens?"
"Prevent memory leaks in my controllers."
"Every confirmation in my app is an alertDialog — what should each one actually be?"
"Should this be a Widget or just a <Require>?"
"Tapping my .backup file in iOS Files previews it instead of opening my app."
"My Share button works on Android but does nothing on iOS, with no error."
"Migrate classic Titanium code to modern Alloy patterns."
"What's a clean way to organize services in an Alloy app?"
```
Key features:
- Quick decision matrix for common questions
- 26 reference guides for deep dives
- Delegates to specialized skills when needed
---
### purgetss
Utility-first styling for Titanium Alloy plus standalone asset and CommonJS commands for Alloy and Classic.
When it activates:
- Setting up PurgeTSS in a project
- Complex layouts (Grid system)
- Declarative animations (`<Animation>` component)
- Icon fonts (Font Awesome, Material Icons)
- Custom color palettes
- Platform-specific styling
- config.cjs configuration
- Classic `Resources/` outputs for branding, density images, semantic colors, fonts, and modules
Example prompts:
```
"How do I set up PurgeTSS in my existing Alloy project?"
"Create a responsive 12-column grid layout."
"Add a fade-in animation when my view appears."
"How do I configure custom colors in config.cjs?"
"How do I use Font Awesome 7 icons?"
"Style this button differently on iOS vs Android."
"Generate image densities for this Classic Titanium app without converting it to Alloy."
"Install Font Awesome and its CommonJS module under Resources in my Classic app."
```
Rules:
- Platform-specific properties require modifiers (e.g., `[platform=ios]`) to prevent cross-platform build failures
- No flexbox (`flex-row`, `justify-between`) -> use `horizontal`/`vertical`
- No `w-full` -> use `w-screen`
- No `p-*` on Views -> use `m-*` on children
- Arbitrary values use parentheses: `w-(100px)`, not `w-[100px]`
---
### ti-ui
UI/UX expert for layouts and platform components.
When it activates:
- Layout systems (composite, vertical, horizontal)
- ListView/TableView optimization
- Event handling and bubbling
- Animations and transforms
- Gestures (swipe, pinch, longpress)
- Orientation handling
- App icons and splash screens
- Android Action Bar / iOS Navigation patterns
- Accessibility (VoiceOver, TalkBack)
Example prompts:
```
"How do I create a high-performance ListView with custom templates?"
"Handle swipe gestures on table rows."
"Set up app icons for all iOS and Android densities."
"Implement pull-to-refresh on a ScrollView."
"How do I make my app accessible for VoiceOver users?"
"How do I configure the Android Action Bar with custom menu items?"
```
Key rules:
- No `Ti.UI.SIZE` in ListView items (causes jerky scrolling)
- Prefer ListView over TableView for large datasets
- Use `dp` units for cross-platform consistency
- Remove global listeners on pause
---
### ti-game
2D game development with the `ti.game` native module — a sprite engine rendered with OpenGL ES 2.0 on Android and Metal on iPhone, iPad and Mac Catalyst, with a mostly shared JS API. Works in Alloy and Classic projects.
When it activates:
- `tiapp.xml` declares `ti.game`, or any file calls `require('ti.game')`
- Sprites, sprite sheets, TexturePacker atlases, frame animations, native tweens
- Physics: gravity and velocity, solid platforms, one-way floors, bouncing, the arcade car model, Newtonian thrust
- Collision groups, invisible trigger zones, enter/exit events, swept AABB for fast bullets, per-axis hitbox tuning with the `debug` overlays
- Native side-wall state, `wallhit` transitions and `wallSlideSpeed` for wall jumps/slides without a JS frame loop
- Raycasts for line of sight, ledge probes and hitscan shots
- A* pathfinding (`findPath`) around tagged obstacles, feeding native patrol paths (`followPath`) and animation chaining (`play(name, { then })`)
- Bitmap-font text sprites with native word wrap, and screen-fixed HUDs inside the scene
- Sprites pinned to other sprites (`attachTo`) — name tags, health bars, shadows, turrets, tracked natively every frame, inheriting the owner's opacity
- Named anchors and percentage strings (`anchor: 'bottom'`, `hitboxScaleY: '55%'`) wherever the engine takes a ratio
- Particle emitters, Verlet ropes, camera follow/zoom/shake/effects, `scrollFactor` parallax, low-latency sound
- Game-clock timers that obey pause and slow motion, texture `unload()` for level streaming, and what LiveView reloads clean up on their own
- Native `TileLayer` maps with visible-cell rendering, Tiled GIDs, solid/one-way cells, live edits and A* integration
- Collision-shape overlays plus the expandable performance HUD and opt-in `performance` telemetry event
- Drag & drop, pinch, rotate, multitouch controls
- Focused keyboard/mouse/gamepad actions, input contexts, canvas focus and native text-field ownership
Example prompts:
```
"Build a flappy-bird style game with ti.game."
"My sprites won't collide — collisionGroup is set on both."
"Add a camera that follows the player with a dead zone."
"How do I make a top-down racer that drifts?"
"Why does my game stutter when I move sprites from setInterval?"
"Add a score HUD that stays put while the camera follows the player."
"Make the guard walk a patrol route and turn around before the ledge."
"Tap to walk, but the player should go around the tree instead of through it."
"Render a 200x200 Tiled map without creating one sprite per tile."
"Show FPS, p95 frame time, draw calls and texture switches while I tune this scene."
"Add wall jumps and a slow wall slide without polling collisions."
```
Key rules:
- JS describes the scene and reacts to events; the engine runs every frame. Never move a sprite from a timer — use velocity, gravity, a tween, `carMode` or `thrust`
- Build the level inside a guarded `resize` handler, never from `Ti.Platform.displayCaps`
- `solidWith` blocks, `collidesWith` reports — they are independent
- Gate wall jumps on `onWallLeft` / `onWallRight`; reserve `wallhit` for transition effects
- A sprite with size but no sheet is an invisible trigger (scores, goals, walls)
- Add a whole level with one `gameView.add([...])` call
- Use `Game.createTileLayer()` for large/static grids; keep sprites for interactive cells and actors
- HUDs are `Game.createText` sprites with `screenFixed: true`, not `Ti.UI.Label` overlays
- `debug: true` means collision shapes; use `debug: { hud: true }` or `performance` for telemetry
- Timers that drive game logic belong on the game clock (`gameView.every`), so a paused game stops spawning
---
### ti-game-assets
Create game art and sound assets as a coherent set: transparent HD masters or strict logical-grid pixel art, animation states, three-layer parallax, synthesized effects/music/ambience, related sound variants and screen-position stereo. `ti-game` owns native game behavior and `ti-synthengine` owns the sound contract; the asset skill coordinates both.
For the processing helpers and development tests, install Python dependencies in a virtual environment:
```bash
python3 -m venv /tmp/titools-assets-env
/tmp/titools-assets-env/bin/pip install -r skills/ti-game-assets/scripts/requirements.txt
TITOOLS_ASSETS_PYTHON=/tmp/titools-assets-env/bin/python npm test
```
Raster drawing generation/editing uses integrated `image_gen`. Authored SVG/procedural pipelines preserve editable sources and deterministically export PNG; offline synthesis can generate WAV. The bundled Python helpers validate alpha, SVG provenance, hashes and WAV headers/payloads. Cleaning writes new files and requires a reviewed protected region or an explicit defined-edge trial. Sound recipes remain source assets even without recorded audio files. Guides cover seamless texture/audio loops and responsible ad transitions through the separate `ti-admob-unified` skill. Technical checks, visual inspection and device listening are reported separately.
### ti-admob-unified
Integrate public **ti.admob.unified 1.0.0** in Alloy or Classic with its official
[repository](https://github.com/macCesar/ti.admob.unified),
[Android downloads](https://github.com/macCesar/ti.admob.unified/releases/tag/android-1.0.0)
and [iOS downloads](https://github.com/macCesar/ti.admob.unified/releases/tag/ios-1.0.0).
Install the core ZIP for each target and only the mediation complements you use.
Requires Titanium SDK 13.4.1.GA, iOS 15+, Android API 24+ and compile SDK 36;
this Apple module does not support Mac Catalyst.
The skill covers consent-first UMP/ATT, synchronous tracking-status queries,
standard/adaptive banners, interstitial, rewarded, rewarded interstitial and
app-open ads. It includes the unchanged copy-ready integration library and
AppLovin, Meta, InMobi, Unity and Liftoff setup/dependency/parity guides.
Rewarded interstitial guidance includes an accurate reward introduction,
visible Skip, SDK-reported rewards and cancellation tied to the presentation
context. Loading an ad alone does not authorize showing it.
The [skill entry point](skills/ti-admob-unified/SKILL.md) routes exact API,
installation, lifecycle and [production guidance](skills/ti-admob-unified/references/production.md)
for app IDs, units, app-ads.txt, privacy options and AdMob/store readiness.
[Source notes](skills/ti-admob-unified/references/source-notes.md) record reviewed
source `0348432`, platform ZIP hashes and native-backed corrections.
A packaged adapter or Google test ad does not prove provider delivery or
production eligibility. Keep configuration/linking, each selected provider's
test delivery and physical-device visual/lifecycle acceptance separate. Game
frequency and pause/audio/input ownership remain application policies.
### ti-synthengine
Sound design and synthesis with the public native `ti.synthengine` 1.0.2 release (public API 1.0.0) for Android and iOS. Local 1.1.0 candidates add capability-gated native per-attack variation while keeping API 1.0.0; they have not been published as releases. Read the [skill entry point](skills/ti-synthengine/SKILL.md) for task routing, exact API references and current source provenance.
Public repository: [macCesar/TiSynthEngine](https://github.com/macCesar/TiSynthEngine).
Download [Android 1.0.2](https://github.com/macCesar/TiSynthEngine/releases/tag/android-1.0.2)
and [iOS 1.0.2](https://github.com/macCesar/TiSynthEngine/releases/tag/ios-1.0.2),
copy the ZIPs into the Titanium app root and follow the [installation guide](skills/ti-synthengine/references/guide.md).
Requires Titanium SDK 13.2.0.GA+, Android compile API35+, and iOS 15+; the Apple package also supports Mac Catalyst.
When it activates:
- `tiapp.xml` declares `ti.synthengine`, or code calls `require('ti.synthengine')`
- Generated UI/game cues, instruments, alarms, chords, percussion, sweeps or binaural headphone placement
- Sustained voices, simultaneous native sequences, shared tempo, selective effects/sends, priorities or live voice controls
- Bounded native attack variation, deterministic seeds, complete effect playback or playable instrument adaptations
- Rejected calls, startup glitches, voice/queue diagnostics, render-load measurements or source/artifact compatibility questions
Example prompts:
```
"Create a short sci-fi laser that sweeps left to right with ti.synthengine."
"Build a playable xylophone without retriggering a bar on every touchmove."
"Move a held spatial motor and change its noise clock and low-pass cutoff without restarting it."
"Run music and a victory cue as independent native sequences, then cancel only the cue."
"Apply reverb to music while keeping UI dry, and change the global tempo."
"Explain what the Android Sim80 headphone result proves about performance."
"Vary repeated impacts natively on local 1.1.0 and retain a clean fallback on published 1.0.2."
```
Key rules:
- Native variation requires both capability and schema announcements; [ranges, seeds and loop behavior](skills/ti-synthengine/references/native-variation.md) are distinct from live edits
- Preserve complete effects and layer gains when adapting or repeating them; read [instruments and effects](skills/ti-synthengine/references/instruments-and-effects.md)
- Read constants and exact ranges from the API; strict option dictionaries reject invalid fields or conflicting pitch sources
- Timed tone/chord `duration` includes release. Native sequence intervals and note lengths are separate; held voices release through their IDs
- Schedule successive sounds with `playSequence`, retain positive accepted IDs and cancel the owner's sequence. `stopAll()` is global panic
- `setTempo` drives beat-based transport and synchronized modulation; millisecond sequences keep fixed timing
- `bus`/`applyTo` select processed categories; explicit `effectSend` overrides that selection. One shared chain and final limiter remain global
- Held spatial position, noise clock and one-pole cutoff support compatible 10 ms updates. A stereo voice cannot become spatial through an update
- Omit both spatial coordinates for stereo; zero coordinates enable binaural center. Do not combine binaural coordinates with stereo pan fields
- Start after layout, keep one lifecycle owner, handle Boolean acceptance and sequence IDs, release held notes on cancellation and shut down during teardown
- Current platform metadata, zero-envelope and diagnostic differences are documented. Host checks and a short accepted listening scene do not establish complete physical maximum-load acceptance
The [retro recipes](skills/ti-synthengine/references/recipes.md) and [interaction/instrument recipes](skills/ti-synthengine/references/recipes-interaction.md) preserve acoustic intent, overlap budgets and cleanup. [Source notes](skills/ti-synthengine/references/source-notes.md) identify the reviewed native commit and evidence limits.
---
## Usage examples and best practices
### Example prompts
Starting a new project:
```
"I'm starting a new Titanium Alloy app for a food delivery service.
Can you help me set up the project structure?"
```
UI development:
```
"Can you create a product listing screen with:
- Pull-to-refresh
- Infinite scroll pagination
- Image caching
- Swipe-to-delete"
```
API integration:
```
"Can you build a complete authentication flow with:
- Login/Register screens
- JWT token management
- Secure storage
- Auto-refresh tokens"
```
Performance optimization:
```
"My app is slow - the ListView scrolls poorly and memory usage is high. How do I optimize it?"
```
Migration:
```
"I have a legacy Titanium classic app from 2015. Can you help me migrate it to modern Alloy?"
```
Platform-specific features:
```
"How do I implement Apple Sign-In for iOS and Google Sign-In for Android?"
```
Debugging:
```
"How do I fix "Alloy is not defined" in my lib file?"
```
Codebase analysis (using agent):
```
"Use the ti-pro agent to analyze this project and:
- review the overall architecture
- identify memory leak patterns
- check for common anti-patterns
- suggest improvements"
```
### Tips for better results
1. Be specific. Instead of "Make a list", try "Can you create a ListView with user avatars, names, and swipe actions?"
2. Provide context. Instead of "How do I fix this error?", try "I'm getting this error when compiling: [error message]. Here's my code: [code]"
3. Ask for architecture first. For complex features, start with "How should I architect a real-time chat feature?" then follow up with implementation details.
4. Mention constraints. "Build a settings screen. Must work offline and sync when connected."
5. Reference existing code. "Here's my current controller. How can I improve memory management?"
See [example prompts](docs/examples.md) for requests covering every public skill.
---
## CLI reference
### titools install
Installs Titanium skills, the ti-pro agent, slash commands, and platform symlinks.
```bash
titools install [options]
```
Options:
| Option | Description |
| --------------- | ------------------------------------------------------------------- |
| `-l, --local` | Install skills locally in the current project (`./.agents/skills/`) |
| `-a, --all` | Install to all detected platforms without prompting |
| `--path <path>` | Install to a custom path (skips symlink setup) |
Behavior depends on where you run it:
| Context | Behavior |
| -------------------------- | --------------------------------------------------------------------- |
| Outside a Titanium project | Installs skills globally to `~/.agents/skills/` |
| Inside a Titanium project | Prompts you to choose: Global or Local installation |
| With `--local` flag | Installs skills locally to `./.agents/skills/` in the current project |
What it does:
- Installs the 13 TiTools skills (global or local depending on context)
- Installs ti-pro agent for Claude Code
- Installs the `/ti-check`, `/ti-new-screen` and `/ti-audit` slash commands into `~/.claude/commands/`
- Detects installed AI platforms and lets you choose which to link (only Claude Code needs platform symlinks; Gemini CLI and Codex CLI auto-discover from `~/.agents/skills/`)
- Creates symlinks from `~/.claude/skills/` to the central `~/.agents/skills/`
- Skips any skill or command already served by an enabled marketplace plugin, and removes a duplicate left by an earlier install
- Cleans up legacy artifacts (`alloy-expert` skill, `ti-researcher` agent, redundant Gemini/Codex symlinks)
- If run inside a Titanium project, prompts to run `titools sync` afterward
- Installs Claude Code SessionStart hook for auto-updates
### titools auto-update
Checks for updates and applies them silently. Designed to run from the Claude Code SessionStart hook, but can also be used manually.
```bash
titools auto-update # Show progress
titools auto-update --silent # No output (for hooks)
```
Options:
| Option | Description |
| -------------- | --------------------------------- |
| `-s, --silent` | Suppress all output except errors |
What it does:
1. Checks a local cache (`~/.titools/last-check.json`) — if already checked today, exits immediately
2. Queries npm for the latest version
3. If a new version is available, runs `npm update -g @maccesar/titools`
4. Syncs skills and refreshes platform symlinks
5. If inside a Titanium project, updates existing Knowledge Index files
6. Writes the cache so it won't check again for 24 hours
The hook is installed automatically by `titools install` when Claude Code is selected. It runs `titools auto-update --silent` at the start of every Claude Code session.
### titools status
Shows a quick overview of your installation.
```bash
titools status
```
Displays: version, skills count, agent, hook status, last update check, platform symlinks, and project Knowledge Index status (if inside a Titanium project).
### titools doctor
Diagnoses installation health.
```bash
titools doctor
```
Checks: skill directories exist, symlinks are valid (not broken), agent is installed, slash commands are installed, hook is configured, cache is readable, Knowledge Index version matches CLI version. Reports issues with fix suggestions.
It also reports the marketplace plugin's state, which changes what "healthy" means:
| Plugin state | What doctor reports |
| --------------------------------- | ---------------------------------------------------------------------- |
| Enabled | Claude Code is served by the plugin — missing mirrors are correct |
| Not installed | Skills reach Claude Code through npm mirrors — mirrors must be present |
| Uninstalled, cache directory left | Warns and prints the `rm -rf` that clears the leftover |
### titools sync
Generates a compressed knowledge index inside your project's instruction files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`).
Important: This command only works inside a Titanium project (requires `tiapp.xml`). The knowledge index is project-specific. It detects your SDK version and points to the installed skill references.
```bash
titools sync [path] [options]
```
Arguments:
| Argument | Description |
| -------- | -------------------------------------------- |
| `[path]` | Project path (defaults to current directory) |
Options:
| Option | Description |
| --------------- | ------------------------------------------ |
| `-f, --force` | Overwrite existing files without prompting |
| `-v, --verbose` | Show detailed diagnostics |
What it does:
- Verifies you're inside a Titanium project (`tiapp.xml`)
- Detects Titanium SDK version from `tiapp.xml`
- Prompts you to select which files to sync: `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`
- Inserts or updates a compressed knowledge index block in selected files
- Removes knowledge blocks from unselected files
- Creates files if they don't exist
### titools update
Checks whether a newer `titools` CLI version is available on npm, then syncs installed skills and agents from the currently installed package.
```bash
titools update [options]
```
Options:
| Option | Description |
| ------------- | ------------------------------------------ |
| `-l, --local` | Update local skills in the current project |
Behavior depends on where you run it:
| Context | Behavior |
| --------------------------------------------------------------- | ----------------------------------------------------------- |
| Outside a Titanium project | Updates global skills in `~/.agents/skills/` (if installed) |
| Inside a Titanium project (local skills only) | Updates local skills automatically |
| Inside a Titanium project (both local and global) | Prompts you to choose: Global or Local |
| Inside a Titanium project (with existing knowledge index files) | Also refreshes `AGENTS.md`/`CLAUDE.md`/`GEMINI.md` |
What it does:
1. Checks npm for the latest CLI version
2. If a newer version exists, it shows the update command `npm update -g @maccesar/titools`
3. It exits without changing skills, agents, or knowledge files until the CLI is updated
4. If the CLI is current, it syncs skills and agents from the installed package (no download needed)
5. Updates platform symlinks only for platforms that already have them
6. Cleans up legacy artifacts (`alloy-expert` skill, `ti-researcher` agent)
7. Auto-syncs knowledge index files if they exist in the current project
Note: This command syncs knowledge packages and agents from your installed CLI. To get new features, first update the CLI with `npm update -g @maccesar/titools`, then run `titools update` again.
### titools remove
Removes skills, agents, symlinks, and knowledge index blocks.
```bash
titools remove [options]
```
Options:
| Option | Description |
| ------------- | -------------------------------------------- |
| `-l, --local` | Remove local skills from the current project |
What it does:
- Detects all installed components (skills, agents, symlinks, knowledge blocks)
- Prompts you to select what to remove:
- ti-pro agent for Claude Code
- Knowledge index blocks from instruction files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`)
- Skills from global (`~/.agents/skills/`) or project directory
- Platform symlinks from global or project directory
- Current or retired slash commands, selected separately for home and project
- Home and project mirror selections always target their named directory, including with `--local`
- Mirror removal is not preselected
- Removes both current and legacy artifacts
- Removes Claude Code auto-update hook
- Cleans up cache directory (`~/.titools/`)
### Verify installation
```bash
titools status # Quick overview of everything
titools doctor # Diagnose any issues
titools --version # CLI version only
```
---
## Community-Discovered Patterns
The TiTools skills include **Community-Discovered Patterns** — verified iOS behaviors not present in the official Titanium documentation. These sections are protected from removal during skill audits.
### Large Title + ScrollView (iOS)
When using Large Titles with a ScrollView inside NavigationWindow or TabGroup, three Window properties must be set together. Without all three, the ScrollView content overlaps behind the navigation bar — or the large title renders with a visible delay.
| Class | Property | Purpose |
| -------------------------------- | ---------------------------- | ----------------------------------------------------- |
| `auto-adjust-scroll-view-insets` | `autoAdjustScrollViewInsets` | Adjusts ScrollView insets to prevent content overlap |
| `extend-edges-all` | `extendEdges` | Content extends behind bars (blur/translucent effect) |
| `large-title-enabled` | `largeTitleEnabled` | Large title that collapses on scroll |
**Recommended:** set the base properties as global Window defaults in `config.cjs`:
```js
module.exports = {
theme: {
Window: {
ios: {
apply: 'auto-adjust-scroll-view-insets extend-edges-all status-bar-style-light-content'
}
}
}
};
```
Then only add `large-title-enabled` per-window as needed:
```xml
<Window title="Home" class="large-title-enabled">
<ScrollView class="vertical w-screen" contentHeight="Ti.UI.SIZE">
<!-- Content starts below the nav bar automatically -->
</ScrollView>
</Window>
```
This pattern is documented across four bundled TiTools skills: `ti-ui`, `ti-expert`, `purgetss`, and `ti-api`, which covers the underlying Window properties.
---
## Skill contents summary
| Skill | SKILL.md | References |
| ---------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ti-reuse-first | Reuse Before You Write | 5 files (the ladder, Alloy reuse, indirection, PurgeTSS reuse, diagnostics) |
| ti-expert | Architecture + Implementation | 27 files (patterns, feedback surfaces, file type association, sharing, testing, security, etc.) |
| purgetss | Setup + Critical Rules | 39 files (Classic compatibility, grid, animations, icons, class-index, SVG pipeline, etc.) |
| ti-ui | UI Rules + Platform Diffs | 14 files (layouts, lists, gestures, etc.) |
| ti-game | Native 2D Game Workflow | 12 files (API, input, source notes, setup, physics, patterns, recipes, tile maps, debugging, roadmap) |
| ti-game-assets | Visual and Sound Assets | 10 guides and a manifest example; alpha and contract validation scripts |
| ti-admob-unified | Unified Advertising | 20 Markdown references including production, rewarded interstitial, mediation parity, integration library guidance, provenance and game monetization; source/hash checks and official example assets |
| ti-synthengine | Native Sound Synthesis | 17 Markdown references (14 official parts, 2 curated recipe guides, maintenance notes), complete validation reports/evidence and a reversible source hash manifest |
| ti-api | Titanium API | 20 references for core/platform APIs and native modules |
| ti-guides | SDK Fundamentals | 16 references for setup, configuration, CLI and distribution |
| ti-howtos | Native Integrations | 18 references for platform features and integration workflows |
| alloy-guides | Alloy MVC | 11 references for controllers, views, models, styling and widgets |
| alloy-howtos | Alloy CLI and Debugging | 6 references for commands, configuration and practical workflows |
---
## Troubleshooting
### Skill not activating?
If the AI doesn't seem to use Titanium knowledge:
1. Mention "Titanium" or "Alloy" explicitly in your prompt
2. Be more specific about what you're building
3. Reference the technology stack
4. Try explicit invocation: "Use the purgetss skill for styling questions"
### Getting wrong suggestions?
If the AI suggests patterns you don't use (for example, PurgeTSS when you're not using it):
1. The skill may not have detected your project type correctly
2. Explicitly mention your stack: "I'm using Classic Titanium, not Alloy"
3. Be more specific about what you're building
### PurgeTSS not detected?
If the purgetss skill doesn't activate for your PurgeTSS project:
1. Verify `purgetss/` folder exists in project root
2. Check that `purgetss/config.cjs` exists
3. In Classic, check for generated `Resources/lib/purgetss.*.js` modules
4. Mention "PurgeTSS" explicitly in your prompt
### Wrong advice?
If the AI suggests incorrect patterns (like flexbox):
1. Remind it you're using PurgeTSS
2. Reference the correct pattern from memory
3. Ask to check the PurgeTSS rules
### Need more detail?
Ask the AI to:
```
"Show me the reference documentation for ListView performance"
"What does the ti-expert skill say about memory cleanup?"
```
### titools command not found?
If the command is not found:
```bash
# Verify installation
npm list -g @maccesar/titools
# Re-install
npm install -g @maccesar/titools
```
### Knowledge index not working?
If your AI doesn't use the knowledge index information:
1. Verify AGENTS.md/CLAUDE.md/GEMINI.md exists in your project root
2. Check that your AI supports these files
3. Try explicitly referencing: "Check the AGENTS.md documentation"
### Version mismatch warning?
The knowledge index is based on the latest documentation. Be cautious when using newer APIs in older projects.
---
## Uninstall
```bash
# Remove the CLI
npm uninstall -g @maccesar/titools
# Remove knowledge packages and agent
titools remove
```
Note: `titools remove` can remove the knowledge index blocks from your project files, but it does not delete the files themselves.
---
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for development, skill registration,
public repository boundaries and the release workflow.
---
## Credits
Created by César Estrada ([@macCesar](https://github.com/macCesar)), creator of [PurgeTSS](https://github.com/macCesar/purgeTSS).
## License
MIT License - Free to use, modify, and distribute.
---
## Resources
- [Titanium SDK](https://titaniumsdk.com/)
- [PurgeTSS](https://purgetss.com/)
- [TiDev Community](https://tidev.io/)
- [Claude Code Skills](https://docs.anthropic.com/en/docs/claude-code)
- [Gemini CLI Skills](https://geminicli.com/docs/cli/skills/)
- [Codex CLI Skills](https://developers.openai.com/codex/skills/)