Skip to main content

Tutorial 1: Exploring a New Codebase

You've just cloned a project you've never seen before. It has hundreds of files and no one to ask. This tutorial shows how to use CIAK to get oriented quickly — finding where things live, what connects to what, and how the codebase is structured.

What you'll use: ciak init, ciak scan, ciak search, ciak related-files

Time: ~10 minutes

Step 1 — Initialize CIAK in the project​

From the root of the repository, initialize CIAK:

cd /path/to/the-project
ciak init

This creates a .ciak/ directory with a config.toml and registers the project in CIAK's global registry. Your source files are not modified.

Step 2 — Scan the codebase​

Run a scan to build the local index:

ciak scan --parallel

CIAK walks the directory tree, parses every source file with Tree-sitter, extracts symbols (functions, classes, methods, interfaces), and maps their dependencies. Results are stored in .ciak/database.db.

For a large project, --parallel uses all available CPU cores and is significantly faster.

You'll see progress output like:

Scanning /path/to/the-project...
  Processed 1,240 files
  Extracted 18,432 symbols
  Mapped 9,871 dependencies
  Done in 12.3s

Tip: Run ciak scan --watch in a background terminal during development to keep the index current as you edit files.

Step 3 — Search for a concept​

You want to understand how authentication works. Search for it:

ciak search "authentication"

Sample output:

Found 14 results for "authentication"

  src/auth/auth.service.ts:42      AuthService.validateUser()      [method]
  src/auth/auth.guard.ts:15        JwtAuthGuard                    [class]
  src/auth/jwt.strategy.ts:8       JwtStrategy                     [class]
  src/middleware/auth.ts:31        authMiddleware()                [function]
  ...

Now narrow it down — you only care about public TypeScript classes:

ciak search "authentication" --language typescript --visibility public --group-by symbol_type

This groups results by type (Classes, Methods, Functions) so you can scan them at a glance.

Step 4 — Read code in context​

Found something interesting? Add --with-context to see the surrounding code inline:

ciak search "validateUser" --with-context --context-lines 8

Sample output:

src/auth/auth.service.ts:42  AuthService.validateUser()  [method]

  38 |   constructor(
  39 |     private usersService: UsersService,
  40 |     private jwtService: JwtService,
  41 |   ) {}
  42 |
  43 |   async validateUser(username: string, pass: string): Promise<any> {
  44 |     const user = await this.usersService.findOne(username);
  45 |     if (user && user.password === pass) {
  46 |       const { password, ...result } = user;
  47 |       return result;
  48 |     }
  49 |     return null;
  50 |   }

No need to open the file — you can read the implementation right in the terminal.

Step 5 — Find related files​

You're about to modify auth.service.ts. Before you do, find out what else depends on it:

ciak related-files src/auth/auth.service.ts

Sample output:

Related files for: src/auth/auth.service.ts

  src/auth/auth.module.ts          relevance: 0.95  [imports]
  src/auth/auth.controller.ts      relevance: 0.90  [imports]
  src/auth/jwt.strategy.ts         relevance: 0.85  [imports]
  src/users/users.service.ts       relevance: 0.72  [used-by]
  src/app.module.ts                relevance: 0.60  [imports]

You now know exactly which files you'll need to review or update alongside your change. Increase the depth to discover more indirect relationships:

ciak related-files src/auth/auth.service.ts --max-depth 5 --max-files 20

Step 6 — Search within a specific area​

You want to look only at files under src/auth/ and exclude tests:

ciak search "token" --path-patterns "src/auth/**,!**/*.spec.ts" --with-context

The --path-patterns flag accepts comma-separated glob patterns. Prefix a pattern with ! to exclude it.

What you've learned​

In a few commands you can:

  • Index any codebase in seconds with ciak scan
  • Find code by concept with ciak search
  • Read code in context without leaving the terminal
  • Map file dependencies with ciak related-files before making changes

Next steps​