Loading documentation...

Guide

3 min read

Optimal Workflow

When to use Semantiq vs native tools - and how to combine them.

Optimal Workflow

Semantiq doesn't replace Glob, Grep, and Read. It complements them. Here's when to use what.

The tradeoffs

	Semantiq	Native tools
Finds concepts	Yes	No
Regex support	No	Yes
Ranks results	Yes (scores)	No
Dependency graph	Automatic	Manual work
Full file content	No	Yes
Glob patterns	No	Yes
Speed	~45ms	~15ms

Neither is better. They solve different problems.

Quick decision guide

You want to...	Use
Find files matching `*.tsx`	Glob
Find exact text `TODO:`	Grep
Read a file	Read
Find "auth-related code"	semantiq_search
Understand a function	semantiq_explain
See what imports a file	semantiq_deps
Rename something safely	semantiq_find_refs

Tool comparisons

semantiq_search vs Grep

Grep wins when you know the exact text:

Plain Text

Grep("TODO:")  → all TODOs, fast

semantiq_search wins when you know the concept:

Plain Text

semantiq_search("error handling")
→ finds try/catch, error middleware, exception classes

Grep would need you to already know those terms exist.

semantiq_explain vs Read

Read gives you everything — the full file.

semantiq_explain gives you the gist — signature, docs, what's connected.

Use explain first to see if it's what you need. Then Read if you want details.

semantiq_deps vs manual tracing

Manually figuring out "what depends on this file" means:

Read the file
Note its exports
Grep for imports
Repeat for each match

Or just:

Plain Text

semantiq_deps("src/utils/token.ts")
→ 2 imports, 8 dependents, done

semantiq_find_refs vs Grep

Grep finds all text matches. That includes comments, strings, and unrelated variables named the same.

semantiq_find_refs understands scope. It separates definitions from usages and ignores noise.

Workflows

Exploring new code

You just cloned something. Where do you start?

Plain Text

11. Glob("**/*.{ts,tsx}")
2   → see the file structure
3
42. semantiq_search("main entry point")
5   → find where it starts
6
73. semantiq_deps("src/index.ts")
8   → see what it pulls in
9
104. semantiq_search("config")
11   → find settings patterns

Safe refactoring

Before renaming UserService:

Plain Text

11. semantiq_find_refs("UserService")
2   → 12 refs in 8 files. ok.
3
42. semantiq_deps("src/services/user.ts")
5   → see what breaks if you touch it
6
73. Read("src/routes/users.ts")
8   → check the tricky usage
9
104. Make changes
11
125. semantiq_find_refs("UserServiceV2")
13   → verify the rename worked everywhere

Understanding a feature

How does auth work here?

Plain Text

11. semantiq_search("authentication login")
2   → finds handler.ts, middleware.ts, routes.ts
3
42. semantiq_explain("handleAuth")
5   → signature, related symbols
6
73. semantiq_deps("src/auth/handler.ts")
8   → what it uses, what uses it
9
104. Read("src/auth/handler.ts")
11   → now read the actual code

Debugging

Something's throwing AuthenticationError:

Plain Text

11. Grep("AuthenticationError")
2   → src/utils/errors.ts:23 (defined)
3   → src/auth/handler.ts:45 (thrown)
4
52. semantiq_find_refs("handleAuth")
6   → see all call sites
7
83. Read("src/auth/handler.ts", lines 40-60)
9   → see the exact throw condition

The pattern

Plain Text

1DISCOVER          →    UNDERSTAND
2Glob, Grep             semantiq_search
3
4       ↓                      ↓
5
6    ANALYZE          →     READ
7semantiq_deps            Read tool
8semantiq_explain
9
10       ↓
11
12   REFACTOR
13semantiq_find_refs

Native tools for precision. Semantiq for comprehension. Combine both.

Optimal Workflow

When to use Semantiq vs native tools - and how to combine them.

Optimal Workflow

Semantiq doesn't replace Glob, Grep, and Read. It complements them. Here's when to use what.

The tradeoffs

	Semantiq	Native tools
Finds concepts	Yes	No
Regex support	No	Yes
Ranks results	Yes (scores)	No
Dependency graph	Automatic	Manual work
Full file content	No	Yes
Glob patterns	No	Yes
Speed	~45ms	~15ms

Neither is better. They solve different problems.

Quick decision guide

You want to...	Use
Find files matching `*.tsx`	Glob
Find exact text `TODO:`	Grep
Read a file	Read
Find "auth-related code"	semantiq_search
Understand a function	semantiq_explain
See what imports a file	semantiq_deps
Rename something safely	semantiq_find_refs

Tool comparisons

semantiq_search vs Grep

Grep wins when you know the exact text:

Plain Text

Grep("TODO:")  → all TODOs, fast

semantiq_search wins when you know the concept:

Plain Text

semantiq_search("error handling")
→ finds try/catch, error middleware, exception classes

Grep would need you to already know those terms exist.

semantiq_explain vs Read

Read gives you everything — the full file.

semantiq_explain gives you the gist — signature, docs, what's connected.

Use explain first to see if it's what you need. Then Read if you want details.

semantiq_deps vs manual tracing

Manually figuring out "what depends on this file" means:

Read the file
Note its exports
Grep for imports
Repeat for each match

Or just:

Plain Text

semantiq_deps("src/utils/token.ts")
→ 2 imports, 8 dependents, done

semantiq_find_refs vs Grep

Grep finds all text matches. That includes comments, strings, and unrelated variables named the same.

semantiq_find_refs understands scope. It separates definitions from usages and ignores noise.

Workflows

Exploring new code

You just cloned something. Where do you start?

Plain Text

11. Glob("**/*.{ts,tsx}")
2   → see the file structure
3
42. semantiq_search("main entry point")
5   → find where it starts
6
73. semantiq_deps("src/index.ts")
8   → see what it pulls in
9
104. semantiq_search("config")
11   → find settings patterns

Safe refactoring

Before renaming UserService:

Plain Text

11. semantiq_find_refs("UserService")
2   → 12 refs in 8 files. ok.
3
42. semantiq_deps("src/services/user.ts")
5   → see what breaks if you touch it
6
73. Read("src/routes/users.ts")
8   → check the tricky usage
9
104. Make changes
11
125. semantiq_find_refs("UserServiceV2")
13   → verify the rename worked everywhere

Understanding a feature

How does auth work here?

Plain Text

11. semantiq_search("authentication login")
2   → finds handler.ts, middleware.ts, routes.ts
3
42. semantiq_explain("handleAuth")
5   → signature, related symbols
6
73. semantiq_deps("src/auth/handler.ts")
8   → what it uses, what uses it
9
104. Read("src/auth/handler.ts")
11   → now read the actual code

Debugging

Something's throwing AuthenticationError:

Plain Text

11. Grep("AuthenticationError")
2   → src/utils/errors.ts:23 (defined)
3   → src/auth/handler.ts:45 (thrown)
4
52. semantiq_find_refs("handleAuth")
6   → see all call sites
7
83. Read("src/auth/handler.ts", lines 40-60)
9   → see the exact throw condition

The pattern

Plain Text

1DISCOVER          →    UNDERSTAND
2Glob, Grep             semantiq_search
3
4       ↓                      ↓
5
6    ANALYZE          →     READ
7semantiq_deps            Read tool
8semantiq_explain
9
10       ↓
11
12   REFACTOR
13semantiq_find_refs

Native tools for precision. Semantiq for comprehension. Combine both.

Optimal Workflow

Optimal Workflow

The tradeoffs

Quick decision guide

Tool comparisons

semantiq_search vs Grep

semantiq_explain vs Read

semantiq_deps vs manual tracing

semantiq_find_refs vs Grep

Workflows

Exploring new code

Safe refactoring

Understanding a feature

Debugging

The pattern

See Also

Optimal Workflow

Optimal Workflow

The tradeoffs

Quick decision guide

Tool comparisons

semantiq_search vs Grep

semantiq_explain vs Read

semantiq_deps vs manual tracing

semantiq_find_refs vs Grep

Workflows

Exploring new code

Safe refactoring

Understanding a feature

Debugging

The pattern

See Also

Optimal Workflow#

The tradeoffs#

Quick decision guide#

Tool comparisons#

semantiq_search vs Grep#

semantiq_explain vs Read#

semantiq_deps vs manual tracing#

semantiq_find_refs vs Grep#

Workflows#

Exploring new code#

Safe refactoring#

Understanding a feature#

Debugging#

The pattern#

See Also#

Optimal Workflow#

The tradeoffs#

Quick decision guide#

Tool comparisons#

semantiq_search vs Grep#

semantiq_explain vs Read#

semantiq_deps vs manual tracing#

semantiq_find_refs vs Grep#

Workflows#

Exploring new code#

Safe refactoring#

Understanding a feature#

Debugging#

The pattern#

See Also#

Optimal Workflow

The tradeoffs

Quick decision guide

Tool comparisons

semantiq_search vs Grep

semantiq_explain vs Read

semantiq_deps vs manual tracing

semantiq_find_refs vs Grep

Workflows

Exploring new code

Safe refactoring

Understanding a feature

Debugging

The pattern

See Also

Optimal Workflow

The tradeoffs

Quick decision guide

Tool comparisons

semantiq_search vs Grep

semantiq_explain vs Read

semantiq_deps vs manual tracing

semantiq_find_refs vs Grep

Workflows

Exploring new code

Safe refactoring

Understanding a feature

Debugging

The pattern

See Also