How to Run the Osmosis Agent Toolkit in Development Mode with Watch Mode

Run bun run dev from the repository root to start Turbo Repo with TypeScript watch mode across all workspace packages, enabling automatic recompilation as you edit source files.

The Osmosis Agent Toolkit is a TypeScript monorepo that leverages Turbo Repo to orchestrate development workflows. When you need to iterate rapidly on the core utilities or MCP server implementation, the repository provides a unified watch mode that continuously recompiles TypeScript to JavaScript in real-time without manual build steps.

Understanding the Watch Mode Architecture

The development workflow combines Turbo Repo with TypeScript's watch compiler (tsc -w). In turbo.json (lines 8-10), the dev task is configured as "persistent": true, ensuring the process stays alive while monitoring file changes. This setup allows the monorepo to run parallel watch processes across all workspace packages.

According to the source code in jonator/osmosis-agent-toolkit, the root package.json (lines 11-14) defines the entry point as "dev": "turbo run dev". When executed, Turbo Repo locates the dev script in every workspace package and runs them concurrently.

Starting Development Watch Mode

Install Dependencies

First, install all workspace dependencies using your preferred package manager:

bun i

This command is documented in the repository's README (lines 46-55) and prepares all packages for development.

Run Watch Mode Across All Packages

Execute the root dev script to launch TypeScript watch mode for the entire monorepo:

bun run dev

This command invokes Turbo Repo, which simultaneously starts tsc -w for the core package (packages/core/package.json, lines 20-22) and the mcp package (packages/mcp/package.json, lines 24-26). You will see parallel output streams showing compilation status for each workspace.

Run Watch Mode for a Single Package

To focus on a specific workspace without running the entire monorepo, navigate to the package directory and run its individual dev script:

cd packages/mcp
bun run dev

This launches tsc -w only for the MCP server implementation, reducing noise when you are working on isolated changes.

Testing Changes Without Rebuilding

Because the watch mode continuously writes compiled JavaScript to each package's dist/ directory, you can test changes immediately without a separate build step. Once the initial compilation finishes, execute the MCP server directly from the built output:

npx -y @osmosis-agent-toolkit/mcp --mnemonic='$OSMOSIS_MNEMONIC'

Since tsc -w automatically updates dist/index.js whenever you modify source files, stopping and restarting the server loads your latest changes instantly. This workflow eliminates the traditional build-and-run cycle, enabling rapid iteration on the agent toolkit functionality.

Key Configuration Files

The watch mode behavior is defined across four critical files in the repository:

• package.json (root, lines 11-14): Defines "dev": "turbo run dev" to orchestrate the monorepo development pipeline.
• turbo.json (lines 8-10): Marks the dev task as persistent so Turbo Repo keeps the watch processes running indefinitely.
• packages/core/package.json (lines 20-22): Contains the core utilities' watch script using tsc -w.
• packages/mcp/package.json (lines 24-26): Contains the MCP server's watch script using tsc -w.

These configurations work together to ensure that running bun run dev at the repository root spins up persistent, parallel TypeScript compilation for every package in the workspace.

Summary

• Turbo Repo orchestrates parallel tsc -w processes across all workspace packages when you run bun run dev from the root.
• Persistent tasks configured in turbo.json keep the watch mode alive, continuously recompiling TypeScript to dist/ folders.
• No separate build step is required to test the MCP server; the compiled JavaScript in dist/ updates automatically and can be executed immediately with npx.
• Single-package development is supported by running bun run dev within specific package directories like packages/mcp.

Frequently Asked Questions

What package manager should I use with the Osmosis Agent Toolkit?

The repository documentation primarily demonstrates Bun (bun i and bun run dev), but the monorepo is compatible with Yarn and other Node.js package managers. The watch mode functionality depends on Turbo Repo and TypeScript, not the specific package manager used for installation.

Why does the MCP server run from dist/ instead of source TypeScript?

The MCP server (@osmosis-agent-toolkit/mcp) executes from the dist/ directory because Node.js requires JavaScript to run directly. The tsc -w command continuously compiles TypeScript source files into JavaScript within dist/, allowing immediate execution via npx without waiting for manual builds. This approach bridges the gap between development convenience and runtime requirements.

How do I stop the watch mode when finished developing?

Since Turbo Repo configures the dev task as persistent in turbo.json (lines 8-10), the process runs indefinitely until manually terminated. Press Ctrl+C in your terminal to send a SIGINT signal, which stops all parallel tsc -w processes and exits the development watch mode cleanly.

Can I run the toolkit in watch mode if I only modified one file?

Yes. TypeScript's watch mode (tsc -w) performs incremental compilation, meaning it only recompiles files affected by your changes rather than the entire codebase. When you save a file, the compiler detects the modification, updates the corresponding output in dist/, and preserves the watch process for subsequent edits.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}