Project Detection

agnt automatically detects your project type, package manager, and available scripts without any configuration.

How It Works

The detect tool analyzes your project directory to identify:

1. Project Type - Go, Node.js, or Python
2. Package Manager - npm, pnpm, yarn, bun (Node.js) or pip, poetry, pipenv (Python)
3. Project Name - From manifest files (package.json, go.mod, pyproject.toml)
4. Available Scripts - Commands you can run with the run tool

Detection Hierarchy

Projects are detected in priority order:

1. Go - Presence of go.mod
2. Node.js - Presence of package.json
3. Python - Checks pyproject.toml → setup.py → setup.cfg → requirements.txt

If multiple project markers exist, the first match wins.

Usage

Basic Detection

detect {path: "."}

Response for a Node.js project:

{
  "type": "node",
  "package_manager": "pnpm",
  "name": "my-react-app",
  "version": "1.0.0",
  "scripts": ["dev", "build", "test", "lint", "preview"]
}

Detect Specific Directory

detect {path: "./packages/frontend"}

Useful for monorepos where different packages have different project types.

Supported Project Types

Go Projects

Detected by go.mod file. Extracts module name.

{
  "type": "go",
  "name": "github.com/user/myproject",
  "scripts": ["build", "test", "lint", "vet", "fmt"]
}

Default Go scripts:

Script	Command
build	go build ./...
test	go test ./...
lint	golangci-lint run
vet	go vet ./...
fmt	go fmt ./...

Node.js Projects

Detected by package.json. Package manager detected from lockfiles:

Lockfile	Package Manager
pnpm-lock.yaml	pnpm
yarn.lock	yarn
bun.lockb	bun
package-lock.json	npm

{
  "type": "node",
  "package_manager": "pnpm",
  "name": "my-app",
  "version": "2.1.0",
  "scripts": ["dev", "build", "test", "lint", "typecheck"]
}

Scripts are read directly from package.json.

Python Projects

Detected by multiple markers in priority order:

1. pyproject.toml - Modern Python projects (Poetry, Hatch, etc.)
2. setup.py - Traditional setuptools
3. setup.cfg - Declarative setuptools
4. requirements.txt - Basic pip projects

{
  "type": "python",
  "name": "my-django-app",
  "scripts": ["test", "lint", "format", "type-check"]
}

Default Python scripts:

Script	Command
test	pytest
lint	flake8 or ruff check
format	black .
type-check	mypy .

Real-World Examples

Monorepo Detection

my-monorepo/
├── apps/
│   ├── web/           # Node.js (Next.js)
│   │   └── package.json
│   └── api/           # Go
│       └── go.mod
├── packages/
│   └── shared/        # Node.js (library)
│       └── package.json
└── scripts/           # Python (tooling)
    └── pyproject.toml

Detect each project:

detect {path: "./apps/web"}
→ {type: "node", package_manager: "pnpm", scripts: ["dev", "build"]}

detect {path: "./apps/api"}
→ {type: "go", scripts: ["build", "test"]}

detect {path: "./scripts"}
→ {type: "python", scripts: ["lint", "format"]}

CI/CD Integration

Use detection to run the right commands without hardcoding:

# GitHub Actions example
- name: Detect Project
  run: |
    PROJECT_TYPE=$(agnt detect --path . | jq -r '.type')
    echo "PROJECT_TYPE=$PROJECT_TYPE" >> $GITHUB_ENV

- name: Run Tests
  run: |
    if [ "$PROJECT_TYPE" = "node" ]; then
      pnpm test
    elif [ "$PROJECT_TYPE" = "go" ]; then
      go test ./...
    fi

IDE Integration

AI assistants can use detection to provide context-aware suggestions:

User: "How do I run tests?"

AI: [detect {path: "."}]
    → Node.js project with pnpm

AI: "Run tests with: pnpm test

    Or use the run tool:
    run {script_name: "test"}"

Error Handling

No Project Detected

If no project markers are found:

{
  "error": "no project detected",
  "path": "/some/empty/directory"
}

Invalid Path

If the path doesn't exist:

{
  "error": "path does not exist",
  "path": "/nonexistent/path"
}

Best Practices

1. Use Relative Paths - Start with . for the current directory
2. Detect Before Running - Always detect to know available scripts
3. Handle Monorepos - Detect individual packages, not the root
4. Cache Results - Detection is fast but results don't change during a session

Next Steps

Once you've detected your project, use the run tool to execute scripts and the proc tool to manage running processes.