diff --git a/AGENTS.md b/AGENTS.md
index 91dd5a0..2801de4 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -25,7 +25,8 @@ npx vitest run -t "should detect horizontal win for X"
 
 ### Imports
 - Use **double quotes** for local imports, **single quotes** for npm packages
-- No path aliases — use relative `../` and `./` paths
+- Use `@/**/*` for `./src/**/*` import alias
+- Use `@/index` for code in `samples`
 
 ### Formatting
 - **4-space indentation**
diff --git a/src/core/game.ts b/src/core/game.ts
index 4d6470a..5f1c46e 100644
--- a/src/core/game.ts
+++ b/src/core/game.ts
@@ -1,4 +1,4 @@
-import {entity, Entity} from "../utils/entity";
+import {entity, Entity} from "@/utils/entity";
 import {
     Command,
     CommandRegistry,
@@ -9,7 +9,7 @@ import {
     createCommandRunnerContext,
     parseCommandSchema,
     registerCommand
-} from "../utils/command";
+} from "@/utils/command";
 
 export interface IGameContext<TState extends Record<string, unknown> = {} > {
     state: Entity<TState>;
diff --git a/src/core/part.ts b/src/core/part.ts
index 16a5de5..847debf 100644
--- a/src/core/part.ts
+++ b/src/core/part.ts
@@ -1,6 +1,6 @@
-import {Entity} from "../utils/entity";
+import {Entity} from "@/utils/entity";
 import {Region} from "./region";
-import {RNG} from "../utils/rng";
+import {RNG} from "@/utils/rng";
 
 export type Part = {
   id: string;
diff --git a/src/core/region.ts b/src/core/region.ts
index 43c1f22..ea9f907 100644
--- a/src/core/region.ts
+++ b/src/core/region.ts
@@ -1,6 +1,6 @@
-import {Entity} from "../utils/entity";
+import {Entity} from "@/utils/entity";
 import {Part} from "./part";
-import {RNG} from "../utils/rng";
+import {RNG} from "@/utils/rng";
 
 export type Region = {
   id: string;
diff --git a/src/samples/tic-tac-toe.ts b/src/samples/tic-tac-toe.ts
index 928c8b8..a74b4c3 100644
--- a/src/samples/tic-tac-toe.ts
+++ b/src/samples/tic-tac-toe.ts
@@ -1,7 +1,4 @@
-import {createGameCommandRegistry} from '../';
-import type { Part } from '../';
-import {Entity, entity} from "../";
-import {Region} from "../";
+import {createGameCommandRegistry, Part, Entity, entity, Region} from '@/index';
 
 const BOARD_SIZE = 3;
 const MAX_TURNS = BOARD_SIZE * BOARD_SIZE;
diff --git a/src/utils/command/command-registry.ts b/src/utils/command/command-registry.ts
index 73cf615..e91252e 100644
--- a/src/utils/command/command-registry.ts
+++ b/src/utils/command/command-registry.ts
@@ -3,7 +3,7 @@ import type {CommandResult, CommandRunner, CommandRunnerContext, PromptEvent} fr
 import { parseCommand } from './command-parse';
 import { applyCommandSchema } from './command-validate';
 import { parseCommandSchema } from './schema-parse';
-import {AsyncQueue} from "../async-queue";
+import {AsyncQueue} from "@/utils/async-queue";
 
 export type CommandRegistry<TContext> = Map<string, CommandRunner<TContext, unknown>>;
 
diff --git a/tests/core/game.test.ts b/tests/core/game.test.ts
index bc1498a..4c4d726 100644
--- a/tests/core/game.test.ts
+++ b/tests/core/game.test.ts
@@ -1,7 +1,6 @@
 import { describe, it, expect } from 'vitest';
-import { createGameContext, createGameCommand, createGameCommandRegistry, IGameContext } from '../../src/core/game';
-import { Entity } from '../../src/utils/entity';
-import type { PromptEvent } from '../../src/utils/command';
+import { createGameContext, createGameCommand, createGameCommandRegistry } from '@/core/game';
+import type { PromptEvent } from '@/utils/command';
 
 type MyState = {
     score: number;
@@ -77,7 +76,7 @@ describe('createGameContext', () => {
 
 describe('createGameCommand', () => {
     it('should run a command with access to game context', async () => {
-        const { registry } = createGameCommandRegistry<Entity<{ marker: string }>>();
+        const { registry } = createGameCommandRegistry<{ marker: string }>();
         const ctx = createGameContext(registry, { marker: '' });
 
         createGameCommand(registry, 'set-marker <id>', async function (cmd) {
diff --git a/tests/core/region.test.ts b/tests/core/region.test.ts
index e73f1ac..c9c0bb8 100644
--- a/tests/core/region.test.ts
+++ b/tests/core/region.test.ts
@@ -1,8 +1,8 @@
 import { describe, it, expect } from 'vitest';
-import { applyAlign, shuffle, type Region, type RegionAxis } from '../../src/core/region';
-import { createRNG } from '../../src/utils/rng';
-import { entity, Entity } from '../../src/utils/entity';
-import { type Part } from '../../src/core/part';
+import { applyAlign, shuffle, type Region, type RegionAxis } from '@/core/region';
+import { createRNG } from '@/utils/rng';
+import { entity, Entity } from '@/utils/entity';
+import { type Part } from '@/core/part';
 
 describe('Region', () => {
     function createTestRegion(axes: RegionAxis[], parts: Part[]): Entity<Region> {
diff --git a/tests/samples/tic-tac-toe.test.ts b/tests/samples/tic-tac-toe.test.ts
index 129f358..3fb509b 100644
--- a/tests/samples/tic-tac-toe.test.ts
+++ b/tests/samples/tic-tac-toe.test.ts
@@ -7,10 +7,10 @@ import {
     createInitialState,
     TicTacToeState,
     WinnerType, PlayerType
-} from '../../src/samples/tic-tac-toe';
-import {Entity} from "../../src/utils/entity";
-import {createGameContext} from "../../src";
-import type { PromptEvent } from '../../src/utils/command';
+} from '@/samples/tic-tac-toe';
+import {Entity} from "@/utils/entity";
+import {createGameContext} from "@/";
+import type { PromptEvent } from '@/utils/command';
 
 function createTestContext() {
     const ctx = createGameContext(registry, createInitialState);
diff --git a/tests/utils/async-queue.test.ts b/tests/utils/async-queue.test.ts
index b4c23e7..61bd2f9 100644
--- a/tests/utils/async-queue.test.ts
+++ b/tests/utils/async-queue.test.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { AsyncQueue } from '../../src/utils/async-queue';
+import { AsyncQueue } from '@/utils/async-queue';
 
 describe('AsyncQueue', () => {
     describe('push', () => {
diff --git a/tests/utils/command-inline-schema.test.ts b/tests/utils/command-inline-schema.test.ts
index 4b9d634..d937610 100644
--- a/tests/utils/command-inline-schema.test.ts
+++ b/tests/utils/command-inline-schema.test.ts
@@ -5,7 +5,7 @@ import {
     validateCommand,
     parseCommand,
     type CommandSchema,
-} from '../../src/utils/command';
+} from '@/utils/command';
 
 describe('parseCommandSchema with inline-schema', () => {
     it('should parse schema with typed params', () => {
diff --git a/tests/utils/command-runner.test.ts b/tests/utils/command-runner.test.ts
index e4c76aa..94e74f9 100644
--- a/tests/utils/command-runner.test.ts
+++ b/tests/utils/command-runner.test.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { parseCommandSchema } from '../../src/utils/command/schema-parse';
+import { parseCommandSchema } from '@/utils/command/schema-parse';
 import {
     createCommandRegistry,
     registerCommand,
@@ -10,8 +10,8 @@ import {
     createCommandRunnerContext,
     type CommandRegistry,
     type CommandRunnerContextExport,
-} from '../../src/utils/command/command-registry';
-import type { CommandRunner, PromptEvent } from '../../src/utils/command/command-runner';
+} from '@/utils/command/command-registry';
+import type { CommandRunner, PromptEvent } from '@/utils/command/command-runner';
 
 type TestContext = {
     counter: number;
diff --git a/tests/utils/command-schema.test.ts b/tests/utils/command-schema.test.ts
index 4f0661a..d0284d5 100644
--- a/tests/utils/command-schema.test.ts
+++ b/tests/utils/command-schema.test.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { parseCommand, parseCommandSchema, validateCommand } from '../../src/utils/command';
+import { parseCommand, parseCommandSchema, validateCommand } from '@/utils/command';
 
 describe('parseCommandSchema', () => {
     it('should parse empty schema', () => {
diff --git a/tests/utils/command.test.ts b/tests/utils/command.test.ts
index 3247887..9037e2d 100644
--- a/tests/utils/command.test.ts
+++ b/tests/utils/command.test.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { parseCommand, type Command } from '../../src/utils/command';
+import { parseCommand, type Command } from '@/utils/command';
 
 describe('parseCommand', () => {
     it('should parse empty string', () => {
diff --git a/tests/utils/entity.test.ts b/tests/utils/entity.test.ts
index 76a79fe..520415c 100644
--- a/tests/utils/entity.test.ts
+++ b/tests/utils/entity.test.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { createEntityCollection, Entity, entity } from '../../src/utils/entity';
+import { createEntityCollection, Entity, entity } from '@/utils/entity';
 
 type TestEntity = {
     id: string;
diff --git a/tests/utils/rng.test.ts b/tests/utils/rng.test.ts
index 9d5d9ea..24811ab 100644
--- a/tests/utils/rng.test.ts
+++ b/tests/utils/rng.test.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { createRNG } from '../../src/utils/rng';
+import { createRNG } from '@/utils/rng';
 
 describe('createRNG', () => {
     it('should create RNG with default seed', () => {
diff --git a/tsconfig.json b/tsconfig.json
index 7662224..5733bc5 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -11,7 +11,11 @@
     "declaration": true,
     "declarationMap": true,
     "outDir": "./dist",
-    "rootDir": "./src"
+    "rootDir": "./src",
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
   },
   "include": ["src/**/*"],
   "exclude": ["node_modules", "dist", "tests"]
diff --git a/tsup.config.ts b/tsup.config.ts
index 535937f..229a881 100644
--- a/tsup.config.ts
+++ b/tsup.config.ts
@@ -1,4 +1,7 @@
 import { defineConfig } from 'tsup';
+import { fileURLToPath } from 'url';
+
+const srcDir = fileURLToPath(new URL('./src', import.meta.url));
 
 export default defineConfig({
   entry: ['src/index.ts'],
@@ -6,4 +9,9 @@ export default defineConfig({
   dts: true,
   clean: true,
   sourcemap: true,
+  esbuildOptions(options) {
+    options.alias = {
+      '@': srcDir,
+    };
+  },
 });
diff --git a/vitest.config.ts b/vitest.config.ts
index 8996a04..e6f0b12 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -6,4 +6,9 @@ export default defineConfig({
     environment: 'node',
     include: ['tests/**/*.test.ts'],
   },
+  resolve: {
+    alias: {
+      '@/': new URL('./src/', import.meta.url).pathname,
+    },
+  },
 });