forge workspace

Manage workspaces for semantic search and code indexing

The workspace command group manages semantic code search, allowing you to index directories and perform intelligent queries across your codebase.

Usage

forge workspace [SUBCOMMAND] [OPTIONS]

Subcommands

sync

Synchronize a directory for semantic search by indexing its contents.

forge workspace sync [PATH] [OPTIONS]

path · path · default: "."

Path to the directory to sync. Defaults to current directory.

forge workspace sync
forge workspace sync ~/projects/myapp
forge workspace sync /path/to/repo

--batch-size · number · default: "100"

Number of files to process concurrently.

forge workspace sync --batch-size 50
forge workspace sync . --batch-size 200

list

List all indexed workspaces.

forge workspace list [OPTIONS]

--porcelain · boolean · default: "false"

Output in machine-readable format.

Alias: -p

forge workspace list --porcelain
forge workspace list -p

query

Query the workspace using semantic search.

forge workspace query <QUERY> [PATH] [OPTIONS]

query · string · required

Search query.

forge workspace query "authentication logic"
forge workspace query "error handling"

path · path · default: "."

Path to the directory to search. Defaults to current directory.

forge workspace query "database queries" .
forge workspace query "API endpoints" ~/projects/api

--limit · number · default: "10"

Maximum number of results to return.

Alias: -l

forge workspace query "tests" -l 20
forge workspace query "config" --limit 5

--top-k · number · default: "none"

Number of highest probability tokens to consider (1-1000).

forge workspace query "imports" --top-k 100

--use-case · string · required

Describe your intent or goal to filter results for relevance.

Alias: -r

forge workspace query "http" -r "finding API route handlers"
forge workspace query "test" --use-case "locating integration tests"

--starts-with · string · default: "none"

Filter results to files starting with this prefix.

forge workspace query "utils" --starts-with src/
forge workspace query "config" --starts-with packages/core

--ends-with · string · default: "none"

Filter results to files ending with this suffix.

forge workspace query "tests" --ends-with .test.ts
forge workspace query "types" --ends-with .d.ts

info

Show workspace information for an indexed directory.

forge workspace info [PATH]

path · path · default: "."

Path to the directory to get information for. Defaults to current directory.

forge workspace info
forge workspace info ~/projects/myapp

delete

Delete one or more workspaces.

forge workspace delete <WORKSPACE_ID>...

workspace_ids · string[] · required

Workspace IDs to delete. Multiple IDs can be specified.

forge workspace delete abc123
forge workspace delete abc123 def456 ghi789

status

Show sync status of all files in the workspace.

forge workspace status [PATH] [OPTIONS]

path · path · default: "."

Path to the directory to check status for. Defaults to current directory.

forge workspace status
forge workspace status ~/projects/myapp

--porcelain · boolean · default: "false"

Output in machine-readable format.

Alias: -p

forge workspace status --porcelain
forge workspace status . -p

init

Initialize an empty workspace for the provided directory.

forge workspace init [PATH]

path · path · default: "."

Path to the directory to initialize as a workspace. Defaults to current directory.

forge workspace init
forge workspace init ~/projects/newapp

Examples

Sync Current Directory

forge workspace sync

Example output:

Indexing workspace: /home/user/projects/myapp

▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ 100%

✓ Indexed 1,247 files in 23 seconds

Sync with Custom Batch Size

forge workspace sync ~/projects/large-repo --batch-size 200

List All Workspaces

forge workspace list

Example output:

Indexed Workspaces:

ID       Path                              Files   Last Synced
abc123   /home/user/projects/myapp        1,247   2024-01-15 10:23
def456   /home/user/projects/api          856     2024-01-14 16:45
ghi789   /home/user/projects/frontend     2,341   2024-01-13 09:12

Query Workspace

forge workspace query "authentication logic" -r "finding login implementation"

Example output:

Search Results:

1. src/auth/login.ts (score: 0.94)
   Implementation of user authentication and session management

2. src/middleware/auth.ts (score: 0.87)
   Authentication middleware for API routes

3. tests/auth.test.ts (score: 0.82)
   Integration tests for authentication flow

Query with Filters

forge workspace query "error handling" \
  --limit 5 \
  --starts-with src/ \
  --ends-with .ts \
  -r "finding error handling patterns"

View Workspace Status

forge workspace status

Example output:

Workspace Status: /home/user/projects/myapp

Status      Files
Indexed     1,247
Modified    3
New         5
Deleted     2

Out of sync files:
  M  src/auth/login.ts
  M  src/api/users.ts
  M  README.md
  A  src/utils/new-helper.ts
  A  tests/new-test.test.ts
  D  old-file.ts

Run 'forge workspace sync' to update the index.

Get Workspace Info

forge workspace info

Example output:

Workspace Information:

  ID:           abc123
  Path:         /home/user/projects/myapp
  Files:        1,247
  Total size:   12.4 MB
  Last synced:  2024-01-15 10:23
  Created:      2024-01-10 14:30

Delete Workspace

forge workspace delete abc123

Example output:

✓ Workspace deleted: abc123

Initialize New Workspace

forge workspace init ~/projects/newapp

Example output:

✓ Workspace initialized: /home/user/projects/newapp
  Run 'forge workspace sync' to index files.

Use Cases

Finding Specific Code Patterns

forge workspace query "database migrations" \
  -r "locating migration files" \
  --ends-with .sql

Locating Test Files

forge workspace query "user authentication" \
  -r "finding relevant test files" \
  --starts-with tests/ \
  --ends-with .test.ts

Exploring New Codebase

forge workspace query "entry point" \
  -r "finding main application entry points" \
  --limit 3

Machine-Readable Output

forge workspace list --porcelain | jq '.workspaces[] | select(.files > 1000)'
forge workspace status --porcelain

Storage Location

Workspace indexes are stored in:

~/.local/share/forge/workspaces/

Performance Tips

• Use --batch-size to adjust indexing speed based on your system
• Larger batch sizes (200-500) work well for SSDs
• Smaller batch sizes (50-100) may be better for HDDs
• Re-sync periodically to keep the index up to date

Related Commands

• forge - AI assistant can use workspace search automatically
• forge list workspace - Alternative way to list workspaces

Notes

• Workspaces must be synced before querying
• The sync command respects .gitignore files
• Semantic search uses AI embeddings for intelligent matching
• Query results are ranked by relevance
• Use --use-case to improve result relevance
• File filters (--starts-with, --ends-with) narrow results efficiently